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• Easy Installation 
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today! 
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1+ 

10+ 
50+ 
100+ 



14.95 
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10.00 
9.00 



Sales Tax 



Kansas residents 6%] 



Shipping«Handling 



Add $2.00 / Order 
Overseas add $5.00 



Nite Owl Productions 

Slide-On Battery Dept. A j 
5734 Lamar Avenue i 
Mission, KS 66202 i 
.__USA I 
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New kit restores your Apple Has 

and 

saves you the hassle and expense 
of normal solder type batteries. 

If you purchased an Apple IIGS computer before August 
1989 (51 2K model), a Lithium battery was soldered onto the 
computer board at the factory and the internal clock started 
ticking. It is just a matter of time until the battery runs out of juice 
and your computer forgets what day it is and any special settings 
you have selected in the Control Panel. 

If the software you are running uses the date and time to 
keep track of records you could be in for real trouble when the 
clock runs out. The IIGS is also known to lose disk drives along 
with numerous other side effects caused by a dead battery. 

Before the introduction of Nite Owl's Slide-On battery, the 

normal method for replacing the IIGS battery was to pack your 
computer up and take it to your local Apple dealer. The service 
department would solder on a new one and charge you a small 
fee, usually between $40 and $80. That was very inconvenient, 
time consuming, and expensive for the typical computer owner. 

Slide-On battery replacement is not much more difficult 
than changing a light bulb. Using wire cutters, scissors, or nail 
dippers, the old battery is removed leaving the original wires still 
soldered to the mother board. The new Slide-On battery has 
special terminals which have been designed to fit onto the old 
battery wires. It usually takes only a couple of minutes. 
Complete, easy-to-follow instructions are included with every kit. 

Typically, our customers have reported that the original 
equipment batteries have an average life expectancy of 2 to 3 
years. This is about half as long as they were supposed to last. 
Slide-On replacement kits include Heavy Duty batteries which 
should provide for a longer battery service life. 

We highly recommend that every IIGS owner keep a spare 
battery on hand, ready for when the inevitable battery failure 
occurs. These Lithium batteries have a shelf life of over 10 years. 
The Slide-On kits come with a full 90 day satisfaction guarantee. 
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On one hand I feel the sUghtest bit sacrilegious pub- 
lishing a brand new Apple II technical Journal before 
the corpse of our late , great forebear (CALLA,P,PX,E:i 
has even grown cold. On the other hand, I am pleased 
to have an opportunity to put my money and time 
where my mouth is. I have said for years that the 
Apple II market is still thriving for those who serve it 
well. 

If those of us in Il-dom always listened to "conven- 
tional wisdom", we would have packed it in and 
bought PCs or Macs at least six years ago. In spite of 
the Mac magazines' dire predictions, and Apple's 
troubles notwithstanding. I have it on good authority 
that 1989 was the best year euer for A2-Central, The 
ByteWorks, Applied Engineering, and of course, Ariel 
Publishing. 

And I am far from being pessimistic about the future. 
The fact is that Apple's bottom line difficulties in 1 989 
may eventually serve to reawaken the company hier- 
archy. Industry analysts - both financially oriented 
and those of a more technical ilk - have been pillaging 
the company in the financial press for leaving its roots 
and abandoning the low end market. 

What has happened, friends, is that the rest of the 
business world is now lending some credence to what 
we Apple II folks have been saying all along. 

This is a good thing, though it is but a beginning. 

As one computer coordinator friend of mine said, 
"Apple is out of their collective minds if they think 
we're going to supply our classrooms with Macs." 

Maybe the school districts in Silicon Valley have the 
bucks for it, but in the rest of the USA, the Driver 
Education classes drive used compact cars, not Lam- 
borghinis. Don't get me wrong, the Lamborghini is a 
great car and the Macintosh is a great computer. But 
there is most definitely a profitable place in this world 
for a Toyota - and the Apple II. Lest I become the target 
for abuse, allow me to add that in many ways I believe 
the Apple II is superior to the Macintosh, even in 
performance. And I am willing to bet that Toyota, Inc. 
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makes more moolah than Lamborghini, Inc. 

''She ain't pretty, but she has a 
terrific personality/* 

Though the kiss of death to a 16 year old girl, I hope the 
statement above comes to describe your feelings for 8/ 
1 6. You will not find flash and splash in our pages. You 
won't even find any colors save black, white, and an 
occasional grey. Worse, you'll see page after page of text 
and source code listings. If there's any clip art it will be 
small. 

So do we have some sort of twisted desire to be ugly? Not 
really. It's just that in our two years of working with 
Apple II programmers we have leamed a few things 
(maybe not as quickly as our subscribers would've 
liked, but we did pay attention in class). 

According to our surveys and interviews, you desire 
timely information more than anj^hing else. And lots 
of it. We are therefore going to cram everything we 
possibly can into our monthly allotment of pages. 

That doesn't mean that our format is encased in con- 
crete. On the contrary, we're still brainstorming ideas 
for potential additions to and deletions from this maga- 
zine. And we most definitely do read our mail. If you 
have an opinion, voice it. 



Where's Mike? 

Mike Westerfield and The ByteWorks staff couldn't 
make our deadline this month. It appears we got 8/16 
off the ground a little too fast for some! Though it pained 
me to go on without an Orca C article (yes, C-fans, we Ve 
been reading your letters), it was more important to be 
on time. Mike and Co. will be with us in the future, 
though, most likely on a bi-monthly basis. 

The same is true of our Micol Advanced BASIC column. 
MAB expert Walter Torres-Hurt needed a little more 
time to whip his contribution into shape. Walter and the 
Micol gang will be with us at least bi-monthly, too. 

Just because Mike and Walter are tackling C, Pascal, 
Orca assembler and MAB topics doesn't mean that the 
rest of you have to sit back and watch. We'd be delighted 
to consider your articles. Call or write for submission 
guidelines (or download them off GEnie's A2PRO RT or 
some other service - we're trying to get them spread all 
over). So you don't have to hunt around looking for our 
address: Ariel PubUshing. Box 398 Pateros, WA 98846 

Our phone: 509/923-2249. Please include a SASE. 



Thanks to the advertisers! 

Our advertisers in this first month of our publication 
have really put their money where their mouths are, too, 
as far as supporting the Apple II community goes. They 
are all companies worthy of your consideration. 

For example. So What Software's new Call Box envi- 
ronment is much more than an Applesoft connection to 
the Ilgs toolbox. Many folks have overlooked the fact it 
produces APW assembly source code output, too, allow- 
ing even you assembly types to design your screens, 
dialogs, etc. in a graphically oriented environment. 

And Night Owl Productions has a product almost aU of 
us Ilgs owners will need sooner or later - an easy to 
install replacement batteiy for your Ilgs. It beats taking 
your motherboard to a dealer (who may sit on it for a 
week). 

USA Micro has some excellent prices on hardware as 
well as a proven track record. Those Laser computers 
are really a good buy, especially for your second Apple. 

KAT Systems of Kansas has some great hard drive 
buys, as well as some of the best prices on Orca 
products youll see. Say, is there some sort of Apple II 
commune in Overland Park, Kansas, or something? 

You 8 bit programmers ought to take a serious look at 
Kitchen Sink Software's MicroDOT. This replacement 
for BASIC.SYSTEM saves a ton of valuable Applesoft 
program space and offers features BASIC.SYSTEM 
never dreamt about. 

And of course, Ariel Publishing has a few things that 
may interest some of you, too! Incidentally, I think that 
it is just too much of a conflict of interest to do much in 
the way of reviewing our own packages. For that reason 
we'll ship them to you "On Approval". You can review 
them yourself. 

Not so incidentally, I'd like to use this last column inch 
to announce an interesting experiment. As a service to 
Apple II programmers and companies, we will provide a 
free half page ad to any Apple II company wishing to 
recruit employees and announce openings. 

Likewise, if you are a programmer looking for work (full 
time, part time, or on a royalty or contract basis), we'll 
offer you a free blurb to advertise yourself (c.f. p. XX). 
The only consideration is that you must be a subscriber, 
our intention being to serve our customers. 

Let's hope Apple, Inc., begins to think the same way. 

== Ross == 




Filtering Out the Riff Raff 



by Steve Stephenson 

As some of you may know, Fve written for Sourceror*s 
Apprentice in the past, and I really was honored when 
Ross asked me to help launch 8/16! Fm not sure why he 
picked me to write this column, but it might have 
something to with my ^bullishness' on Merlin, which IVe 
been happily using since 1982. I'm currently doing all 
of my development in Merlin 16+. and find that it 
completely suits my needs. 

In this column, I plan to show you how to *make the 
magic' in assembly language and how to get more out of 
Merlin. I'll be focusing on 16-bit Ilgs code, and my 
routines will usually be desktop oriented. Unless you 
indicate otherwise, I will assume you are interested in 
how to do the *not so obvious' — in other words, if I had 
trouble figuring it out, someone else is probably also 



having trouble. This month's topic is Just such a case: 
when I first needed to add a filter to a dialog, I couldn't 
find much on the subject. 

When you use _ModalDialog (or any of the _Alert calls), 
your input is handled through filter procedures. The 
Dialog Manager has a built-in filter that allows the 
retum key to act the same as clicking on the default 
button. It also handles cut/copy/paste operations. But 
what are you supposed to do when you want more? The 
Apple Ilgs Toolbox Reference: Volume 1 devotes a 
whopping one page (6-25) to the subject of filter proce- 
dures, and gives no examples! 

To show you how it's done, I've prepared three general 
purpose filters: one to handle the escape key, one to 



Insecticide 

So how can we be correcting errors if this is our first issue? No, we are not psychic (or psychotic) . Rather, 
because 8/ 16 is a reorganization and continuation of The Sowceror*s Apprentice, Znews, and Reboot we 
have had ample time to make boo boos. We like to correct them as soon as possible, though, so if you ever 
find bugs in one of our articles, please drop us a line. 

• Sowceror's Apprentice: We discovered a mysterious insect in Jay Jennings's Generic Start II (Septem- 
ber, 1989). I say "mysterious" because his source code and article were correct on the disk files he gave 
me, but not in the final typeset article (gremlins?). At any rate, at shutdown you need to push the revised 
StartStop record, not the original. Hence line three of the shutdown section should be: PushLong ^tsSRec 

We also discovered that Steve Stephenson's tip on p. 6 of the January, 1990 issue was incorrect. The long 
indexed addressing mode does roll over and cross bank boundaries. Glen Bredon himself cleared that up 
for us (and noted that we forgot to roll over our date on the front cover, too! Shoulda been 1990). 

• Reboot: Subscriber Robert Lanouette wrote to say, "One comment about your Spreadsheet Mockup (Oc- 
tober, 1989). I typed it in, then got double imaging (FILE would become FILEE when I move the cursor 
to BLANK, and BLANK would become BLANKK, etc.) on the top menu line whenever I moved the cursor 
from one menu item to another. When I changed line 740 to read H(I) = PEEK(1403) : PRINT M$(I);SPC(2) 
... the double imaging disappeared." Thanks for clearingg thatt upp, Robertt. 

NOTE: Back issues of Reboot (Applesoft programming), The Sourceror*s Apprentice (Merlin assembly 
language), and Znews (ZBasic programming) are available for $3 per issue as long as supplies last. We've 
been promising an index for God-knows-how-long... soon, real soon. 



gather a hex number, and one to gather a legal ProDOS 
name. (IVe put them all together in one procedure just 
to keep it simple.) 

To set the stage, you should imagine that your program 
uses two different modal dialogs, one for hex input and 
the other for name input. Each of these dialogs has 
three items: an OK button, a Cancel button, and an 
EditLine. As long as you're imagining, I suppose you 
could add a title and a prompt to the dialog, but that's 
not what we're here for. Note: I did not include the 
template to create the dialog. 

The fragment of code at MainProgram should be enough 
to show how to call __ModalDialog with your filter. If you 
want your filter to be used, but would also like to get the 
benefit of the built-in filter, you must set bit 31 of the 
address of your filter when you make the call to _Mo- 
dalDialog. I took the liberty of modifying the super 
macro to set bit 31. It is completely compatible with 
previous code. When you want to set bit 3 1 , simply add 
a semicolon and anything for an additional parameter 
(it's not used for anything other than to indicate that bit 
31 needs to be set). 

When I call __ModalDialog, I pass it a word for the result, 
and the address of my filter. The Dialog Manager 
(among other things) rearranges the stack and calls my 
filter by means of a JSL. The space for the result is still 
there, along with pointers to the dialog's GrafPort, the 
event record, and the item hit. My filter routine may use 
the pointers any way it needs to, but it must pop all of 
them and put a value into the result word when it is 
done. 

On entry, I can count on the Data Bank Register and the 
Direct Page being set to something that is only useful to 
the Dialog Manager (and it must be restored if you 
change it). So, I use the standard opening: save B, reset 
B, save D, reset D. I include a dummy section (at the 
label StackPic) to make it easy to accesjs the stack/ 
dpage variables. 

On exit (see FilterDone), I restore D, B, pop all pointers 
off of the stack, and RTL back to the Dialog Manager. I 
get control again after the Dialog Manager has run it's 
built-in filter and possibly affected the result word. At 
first glance, my stack cleanup may look strange, but it 
is simple, easy to follow, quicker, and takes fewer bytes 
than the standard subtraction method. 

Now, let's get down to the serious business of doing 
something in this filter. I start off with gathering the 
state of the Open Apple key and the key pressed (if any). 
Next. I determine what kind of event this is. If it's a key 
event, then I need to check for the escape key. If it is the 
escape key (or OpenApple-.). I simply make it look like 



a click in the Cancel button. If it's not an escape, I can 
check the key being entered into the EditLine. If it's not 
a key event at all. then I want the Dialog Manager to 
handle it. (Ignore the lines from :validate to :key for now; 
ni get to them later). 

Let's start with the escape key detector (see CheckEs- 
cape). If I don't find an escape, I clear the carry and 
return. Note that the X register, which holds False, will 
remain unchanged; this is to become the result unless 
another routine changes it. A result of False means that 
I didn't find anything interesting and that the Dialog 
Manager should handle the event. On the other hand, 
loading the X register with True signals the Dialog 
Manager that it shouldn't run through it's filter, but to 
just retum the result. 

If I find that escape is being pressed, I simulate a click 
in the cancel button. By protocol, the cancel button is 
always numbered 2 (and the default button, 1), so I 
make the item hit a 2 and set the result word to True. 
While I'm here. I think it's a nice touch to flash the 
button for user feedback. 

The next two routines (HexCheck and NameCheck) are 
meant to be used with an EditLine item in the dialog. 
This presents a new challenge: how to filter the keys I 
am interested in without blocking the special editing 
keys used internally by the Control Manager. The way 
I get around the problem is to trap for the special keys 
first, and pass them through unaltered. 

The HexCheck routine shows how to ignore (or 'swal- 
low') any key that I don't want and how to convert a key 
to some other key. The way this filter works, you could 
pound on the Z key (or any key other than a hex digit) 
all day long and nothing would happen. Additionally, 
lowercase letters are converted as if you had entered 
them in uppercase. To swallow a key, set the Event 
record's What code to null and the Item Hit to null, then 
make sure to tell the Dialog Manager not to look at it 
either by setting the result to True. I suppose you could 
insert a __SysBeep here, if you're into noise. 

The NameCheck routine also starts off with the edit key 
trap, except it makes a special case for the retum key 
(more on that in a moment). It too allows only certain 
characters to pass through, whUe swallowing the oth- 
ers. I also provide a place to change the case if you 
desire. The last thing it does is to mark a flag that this 
name has changed and needs to be re-validated. 

The ProDOSName routine is entirely optional. While 
Apple would discourage the use of such name filtering, 
I would maintain that there are applications where it 
has merit. What it does is check the name that is being 
gathered for meeting ProDOS naming rules and enables 
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the OK button only when a legal name exists. As eveiy 
keystroke might result in this name changing, it needs 
to be checked often, but not so often as to slow every- 
thing to a crawl, I use the flag checked to prevent going 
through the this routine when there is no need to. 

The ProDOSName routine fetches the name string 
(Pascal style) into a buffer. The first test is whether I 
have any string at all; if not, I dim the OK button. 
Otherwise I need to make sure the name begins with a 
letter. I don't need to 

check further as I have already made certain no illegal 
characters could be entered. By the way, I control the 
length of the name by using the value 15 in the 
itemValue field when creating the EditLine. 

There you have it! Custom dialog filter procedures in 
one easy lesson. 
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125 


p1 a 






191 


cmp 


«'9'+l 




126 


pl a 




• ortPi 1 ono rr^oi^"f!. r>"h 1^ 1 


192 


bcc 


: pass 


• C3— 9 = Qood 


127 


pl a 






193 


cmp 






128 


phy 




;re-stk rtl addr 


194 


boo 


: swal 1 ow 




129 


phx 




;re-stk rtl bnk & b 


195 


and 


«$5f 


; alpha, convert it 


130 


plb 




; restore b 


196 




ttoMessage 




131 


rtl 






197 


sta 


[event] , y 


; to uppercase 


132 








198 


omp 


«'F'+1 




133 








199 


bcc 


:pass 


;fl-F = good 


134 








200 








135 


CheckEscape 




201 


: swal 1 ow 




; gobble this key 


136 


Ida 


theKey 




202 


Ida 


110 


;make event nul 1 


137 


cmp 


«$lb 


; escape? 


203 


Idy 


«oWhat 




138 


beq 


: escape 


; yes 


204 


sta 


[event] , y 




139 


cmp 


n ' . ' 


; per i od? 


205 


sta 


[item] 


; & i tem hit = nul 1 


140 


bne 


: none 


; no 


206 


Idx 


«True ; tel 1 DlgHgr we got it 


141 


Ida 


KeyMod i 


f i er ;yes also need OR 


207 


bra 


: done 




142 


bit 


«flppleKey ; got it? 


208 


: pass 






143 


beq 


: none 


; no 


209 


Idx 


«False ; 


let DlgHgr handle it 


144 


: escape 






210 


: done 






145 


Ida 


«2 


;« of cancel btn 


211 


rts 






146 


sta 


[i tem] 


; make it i tem hit 


212 








147 


sta 


temp 


; [also btn prt code) 


213 








148 


"GetControl DItem port; temp 


214 








149 


Pull Long cxHandl e; cancel btn's hndl 


215 


NameCheck 






150 


"H i 1 i teControl 


temp; cxHandl e; fish on 


216 


Ida 


theKey 




151 


'^H i 1 i teControl 


«0; cxHandle ; and off 


217 


Idx 


«keysend- 


keys 


152 


Idx 


«True 


;rl Qot \tr 


218 


Idy 


name : bad 


; if good name. 


153 


sec 




; escaping 


219 


beq 


: ed i ts 


; <cr> is allowed 


154 


bra 


: done 


220 


dex 




;else, swallow it 


155 


: none 




; [X & item unchanged) 


221 


•.edits shortacc 




156 


clc 




;not escaping 


222 


cmp 


keys-1 ^ X 




157 


: done 






223 


1 ongacc 


; special key found 


158 


rts 






224 


beq 


: pass 


159 








225 


dex 






160 


temp duj 







226 


bne 


: ed i ts 




161 


cxHandle adrl 




227 


: normal 






162 








228 


cmp 


« ' . ' 




163 








229 


beq 


: pass 


;dot = ok 


164 


* keys used in an 


EditLine control 


230 


cmp 


«'0' 




165 








231 


bcc 


: swa 1 1 ow 




166 


keys 






232 


cmp 


«'9'+l 




167 


dfb 


$18 


;control-X 


233 


bcc 


:pass 


;0-9 = ok 


168 


dfb 


$19 


;control-V 


234 


cmp 


«'fl' 




169 


dfb 


$06 


;control-F 


235 


bcc 


:swal low 




170 


dfb 


$7f 


; delete 


236 


cmp 


«'Z'+1 




171 


dfb 


$08 


; 1 eft arrow 


237 


bcc 


:pass 


;fi-Z = Ok 


172 


dfb 


$15 


;rt arrow 


238 


cmp 


« • a • 




173 


dfb 


$09 


;tab 


239 


bcc 


:swal low 





240 




cmp 


« 'z ' +1 




241 




bos 


* ^lild 1 1 Olil 


• 3—2 — ok 


242 










243 




Idy 


^ li^ fc^ ^ • w ^■•ip ^5 


• converf 


244 




beq 


; pass 


* r iw 


245 




and 


«$5f 




246 




Idy 


«oMessage 




247 




sta 


[event] , y 


; sneak in sub char 


248 




bra 


:pass 




249 


: SLual 1 ouj 




; gobble this key 


250 




Ida 


410 


; make event nul 1 


251 




Idy 


«oWhat 




252 




sta 


[event] , y 




253 




sta 


[item] 


;& item hit = nul 1 


254 




Idx 


«True ;tel1 DloMgr we got it 


255 




bra 


: done 




255 


: pass 








257 




Idx 


«False ; 


let DlgMgr handle it 


258 


: done 








253 




stz 


checked 


;mark it needing ck 


260 




rts 




261 












♦ = 









263 
264 
265 
266 
267 
268 
269 
270 
271 
272 
273 
274 
275 
276 
277 
278 
279 
280 
281 
282 
283 
284 
285 
286 
287 
288 
283 
230 
231 
232 
233 
234 
235 
236 
237 
238 
233 
300 
301 



ProDOSIMame 

"Get IText port ; «l\lamel tern; «Neuj|\jame 
Ida IMeujIMame ; length of string 
and «$ff 

beq : bad ;none, skip remainder. 



Ida Neuil\lame+1 ; 1st chr mustbe alpha 

and «$5f 

cmp «'Z'+1 

bcs : bad 

cmp « • fl • 

bcs : good 

1 da « i nact I veH i 1 i te ; d i sab 1 e i tem 

bra : h i 1 i te 



:bad 



: good 



1 da «noH i 1 i te ; enab 1 e r tem 



:hi 1 i te 



pha ; [for _H i 1 iteControl ) 

sta name: bad ;0=good; ff=bad 
"GetControlDItem port;«OK ;get hndl 
; [leave handle on stk) 
_H i 1 i teCont ro 1 ; f 1 x the d i mm i ng 
inc checked ;mark it checked 
rts 



KeyMod i f i er dui 
theKey diu 
DialogPtr adrl 
WameOrNumber dm 
uppercase duj 
checked diu 
name: bad diu 
NeuiName ds 16 



; Event mod i f i er b i ts 
; Event key [lo 8 bits} 
;ptr to the dialog 
; f 1 ag : which routine 
; boo 1 ean : f orce upper 
; boolean: name checked 
; boo lean: name is bad 
;name buffer 




DIRLDB.Q 



FUSESTF 







nil 










ft 



Call 

Box« 

The Toolbox 
Programming 
System 



m 

5P. 



UJVSIUIVG? 

(What Vou See Is What Vou Get) 

Four powerful llfVSIIIIVG editors slash program- 
ming time dramatically for Assembly, C, Pascal 
and Applesoft BASIC programs, YES! ... I said 
Applesoft, CALL-BOX includes the first full func- 
tion Applesoft BASIC interface for the ligs toolbox 
as well but let's talk about the editors first. 

• Image Editor . . . 

Create Icons, Cursors, and Pixel images in 
either 640 or 320 mode. 

• Window Editor 

Create Window templates with scroll bars, con- 
trols, etc. plus custom colors. 

• Dialog Editor ... 

Create Dialog templates using Radio buttons, 
Check boxes. Line edit items, text in various 
styles, etc. 

• Menu Editor . . . 

Create Menu templates with keypress equiva- 
lents, checks, diamonds, Font styles, etc. 

All editors output APW source code. Linkable 
object code or resource files to make the best 
match to your current development system. Every- 
thing is accessable from the CALL-BOX Editor 
shell that includes these editors plus File utilities. 
Configuration utilities, programmable application 
launcher and the BASIC interface. 

The CALL-BOX BASIC interface allows the Apple- 
soft programmer to use Super Hi-Res via Quick- 
draw II, desktops, menu bars, windows, ports, 
fonts, dialog boxes, and the cursor linked task 
master system in the ligs. This interface incor- 
porates automated calls to minimize the code 
needed in your BASIC program and has added 
Long Call, Long Poke, Long Peek, and super 
array functions to bring Applesoft up to snuff 
with the additional memory in your ligs. 

All this plus a demo, sample code and bound 
manuals. Fully GS/OS V5.0 compatible and all in 
one place for the first time ever! 



The CALL-BOX TPS $99.00 

Add $4.50 shipping and handling. 
Foreign add $10.50. 

Send check, money order. Visa or MasterCard. 



(714) 964-4298 




so WHAT ^<Zy SOFTWARE 

10221 Slater Ave . #103, Fountain Valley, CA 92708^ 
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Galvanic Skin Response: Getting a Jolt 
From Your Joystick 



by David Gauger II 

Editor: This article - and its successors since we plan 
more - probably seem anachronistic. I certainly know of 
no MacTutor subscribers tearing into their machines! But 
David reminded me that the Apple U has a built-in 
**wirvdow to the world" - and this sets it apart among all 
others, even today. Just try to do a similar project on a 
Macintosh for under $250! Apple II users have always 
been an outgoing, experimental lot I think David's series 
is going to appeal to many of you. Even if you never 
actually build anything, you'll still be amazed at what 
the Apple II can accomplish with such relative ease. 
== Ross == 



and Solid Apple keys (Apple and Option on the Ilgs) are 
connected to pushbutton inputs and 1 in parallel to 
the Joystick pushbuttons. 

Electronically speaking, a pushbutton input simply 
looks at the voltage you give it to determine the button's 
status. If the input sees around volts, the switch is 
considered open (not pushed). If the voltage is 5 volts 
or so, then it's considered closed (pushed). Each of 
these pushbutton (PB) inputs is electrically cormected 
to a pin in the game input port, and, of course, to an 
address in memory. PBO is at address 49249 ($C061), 
FBI is at 49250 ($C062) and PB2 is at 49251 ($C063). 



Interfacing a computer to the outside world is one of 
those things that falls somewhere between art and craft. 
An obvious solution often doesn't work as well as one 
that is creative or offbeat. The answers to many 
interfacing problems lie in rethinking them in new and 
different terms. 

Steve Wozniak*s Disk II controller card is a prime 
example. Prior to his design, disk controller cards used 
many expensive chips. To bring the cost down, Wozniak 
rethought the problem in different terms. Instead of 
relying only on hardware, he implemented many func- 
tions in software, drastically reducing the chip count. 
The solution he developed was so elegant that it's still 
in use today in all Apple II's. Even the Macintosh has 
its version of the controller in its "SuperWoz" chip. 

In this article we will "rethink" the lowly pushbutton 
input in your Apple's game port and show you how to 
build a biofeedback monitor that interfaces to it. The 
usual function of the pushbutton input is to annihilate 
aliens in arcade games, but it's really a one-bit TTL- 
compatible input port capable of much more than 
activating phaser beams. 



Pushbutton Inputs 

Most Apple lis have around 3 pushbutton inputs (the lie 
and IIc+ have 2 and the GS has 4) . No matter what flavor 
your Apple, all such inputs behave in much the same 
way. Like most things related to computers, we number 
them starting with 0. On newer Apples, the Open Apple 



From the software side of things, each pushbutton is 
connected only to the highest bit of its address in 
memory. If the button is pushed, the high bit is set to 
one. Ifit's not pushed, the high bit is zero. Only the high 
bit is significant. Since the high bit is worth 128 in the 
binary number system it is easy to tell when the button 
is pushed. All you need to do is check to see if the value 
at the pushbutton's address is greater than 127. If so. 
the button is pressed. In assembly language, the check 
can be most easily performed with the BMI or BPL 
instructions. 

Most programs use only the minimum information that 
this one-bit input can provide. In an arcade game, when 
you push the button, the phaser fires; when you release 
it, the phaser stops. This is fine, but it leaves much of 
the port's capability untapped. 

Let's rethink the use of this port by shifting our focus 
from a mere on-oiT reading to reading how often it is 
pushed in a given period of time. In other words, the 
rate of button pushing is the significant thing. This 
opens up many possibilities since the port then be- 
comes capable of receiving analog (continuously vari- 
able) data, not just binary (strictly on or off) data. We 
can receive analog data through this port at relatively 
high speeds, since an input port can be checked for 
activity very rapidly in machine language (over 140,000 
times a second in a 1 mhz Apple). 

Biofeedback and Button Pushing 

Biofeedback has been around for a while but surpris- 



ingly few people have ever tried it. Biofeedback meas- 
ures a biological function that correlates to your tension 
level, then feeds that information back to you in real 
time. Immediate feedback enables you to identify the 
things that make you tense, and discover those tech- 
niques most effective in promoting relaxation. 

One biological function that varies with tension level is 
the electrical resistance of your skin. The more tense 
you are, the more you sweat; and the more you sweat, 
the lower your skin resistance . This skin characteristic 
is known as galvanic skin response, or GSR for short. 
Because people often get tense and sweat when not 
telling the truth, GSR is one of several measurements 
made by a lie detector. 

Your health, level of physical activity, the temperature 
of your hands, and even the weather can all have a 
profound effect on your GSR. Your GSR is constantly 
changing. Because it*s not stable, GSR is usually 
interpreted as a relative phenomena. The most com- 
mon GSR technique is to first establish a normal or 
baseline GSR, then note changes or departures from the 
norm. 

Your Apple II computer is well-suited to making the 
GSR measurements for a biofeedback system. Not only 
can the computer collect lots of data, but it can display 
the data graphically, manipulate it, scale it, compare it 
to previous measurements, and store it on disk for later 
use, to name Just a few ideas. The pushbutton input is 
up to the task, but it'll need the help of some simple 
hardware and a small machine language driver. 



Construction 

To get your biofeedback monitoring system up and 
running, youll need to build a device that converts your 
GSR into a signal usable by the pushbutton input. Two 
schematic diagrams (Fig. 1 and 2) are provided, al- 
though the circuit is identical in each case. The only 
difference is the connector used to plug the device into 
your Apple. 

Build your biofeedback monitor in a small plastic 
experimenter's box such as those sold by Radio Shack. 
Use the parts list in Fig. 3 if your computer has a DB- 
9 joystick connector, and the list in Fig. 4 if you have a 
16-pin DIP connector. GSR measurements are col- 
lected with two parallel 5/8 inch by 2 1/2 inch strips of 
common aluminum foil glued to the top of the plastic 
box. Glue the dull side down with rubber cement and 
separate the strips by about 3/8 inch. (See Fig. 5). 

Drill two holes through the plastic, 1/4 inch from the 
same end of each strip. A machine screw's head will 



contact the foil and allow connection between the foil 
and the rest of the circuitry. You can connect the wires 
to the screw with a lug, or by wrapping the wire around 
the screw before tightening the nut. 

It is probably best to mount the components on a small 
1 inch square circuit board cut from a larger one. Once 
it*s working, the circuit board can be stuck to the 
bottom of the box with double sided tape or silicon 
sealer. The rest of the construction is not critical. Use 
common construction techniques, insulating all bare 
wires with black electrician's tape or shrink tubing, and 
checking for shorts caused by things like stray bits of 
solder. 

Double check your wiring, especially the connector 
going to your Apple. Ifs easy to confuse the pins. We're 
only dealing with about 5 volts or so, so danger from 
voltage is not a problem, but wrong connections to the 
gameport could easily damage your Apple. 



The Software 

Next, type in the Applesoft listing and save it on disk 
with the name "BIOFEEDBACK". If you have an assem- 
bler, type in the assembler source code and assemble it 
using the instructions appropriate for your assembler. 
Otherwise, enter the object code from the monitor and 
save it with the command BSAVE 
CYCLETIMER.OBJ,A$303,L$3A. 

These programs work under DOS 3.3 or ProDOS. but 
both files must be on the same disk (and in the same 
directory if you're using ProDOS.) 



Using the Biofeedback System 

To use the complete system, plug your Biofeedback 
monitor into the correct connector on your Apple, tum 
the switch on the biofeedback sensor to the on position, 
and run the program BIOFEEDBACK. Make sure you 
are in 40 column mode with the checkerboard cursor 
active before you start. 

First, the program needs to calibrate itself to your 
baseline GSR. Place two fingers of one hand on the 
aluminum strips. The biofeedback hardware is sensi- 
tive to movement and pressure, so position your arm 
and hand to prevent any pressure variation of your 
fingers on the aluminum strips. Your arm, hand, and 
fingers should be as relaxed as possible. When you are 
ready to begin calibration, hit any key. Calibration 
takes a few seconds, and then the graph of your GSR will 
start appearing on the screen along with many session 
statistics. 
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Figure 1 - Schematic Diagram for DB-9 Connectors 
(Apple lie, llc+, lie, ligs) 
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Figure 2 - Schematic Diagram for 16 pin DIP Connectors 
(Apple II, II+, lie, lIgs) 
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Figure 3: Parts List for DB-9 Version 




Quant i t y 


Oescription 


Radio Shack Part « 


Cost 


1 


555 Timer 


276-1723 


$1 . 19 


2 


.1 rifd Tantalum Capacitors 


272-M32B 


.59 ea 


1 

1 


IK ohm Resistor 


271-023 


1 Q 


1 


DPDT Toggle Switch 


275-626 


2.59 


J ft 


Shielded 2 Conductor Uire 


278-1276 


J , z y 


1 


Experimenter's Box 


270-220 


1 .79 


1 


DB-9 Male Connector 


276-1537 


.99 






Total 






Figure 4: Parts List for 16 Pin DIP Version 




Quant i t y 


Descr i pt i on 


Radio Shack Part « 


(^ost 


1 


555 Timer 


276-1723 


$1.19 


2 


.1 fifd Tantalum Capacitors 


272-H32B 


.59 ea 


1 


IK ohm Resistor 


271-023 


1 


1 


DPDT Toggle Switch 


275-626 


2.59 


3 ft 


Shielded 2 Conductor Uire 


278-1276 


3.29 


1 


Experimenter's Box 


270-220 


1 .79 


1 


16 Pin DIP Header 


*N/fl 


.65 






Total 


$10.88 



* The 16 pin DIP header is not made by Radio Shack anymore. Instead, it is part * 16 HP 
auailable from Jameco Electronics; 1355 Shoreuiay Road, Belmont, Cfl 94002 (415) 592-8097 



Figure 5 - GSR Measuring Device 

Cable to gameport 



Screw goes 
through foil and 
plastic. Connection 
to electronics on 
underside. 

Strips glued to 
case with rubber 
cement. 




Simple on/off switch 



Strips separated by 
about 3/8" inch. 



Strip dimensions: 
2 1/2" long by 5/8" wide. 



As the program runs, it measures your GSR, plots the 
results on the graph portion of the screen, and updates 
the statistics at the bottom. This process continues 
until the graph reaches the right side of the screen at 
which point it wraps around and begins plotting over 
the previous data on the left side of the screen. When 
the graph wraps around, the screen average (SCR AVG) 
starts over; the rest of the statistical data (HIGHEST, 
LOWEST, etc.) is valid and carries over into the new 
screen. 

The top of the screen represents high tension while the 
bottom represents lower tension. Remember that a 
high GSR reading means that your skin resistance was 
high because you weren't sweating, so you must be 
relaxed. Conversely, a low GSR means that you*re 
tense. To represent them on the graph correctly, low 
readings are plotted at the top of the screen and high 
readings at the bottom, an important fact to remember 
when evaluating the statistical data at the bottom of the 
screen. 

Because GSR readings can vary so widely, the program 
provides two sensitivity levels. High sensitivity is the 
most accurate, but the plot is a Jagged line that often 
goes off the screen. You can remedy this situation by 
recalibrating to bring the plot back to the center of the 
screen, or by switching to low sensitivity. Low sensitiv- 
ity attempts to scale the data so that all of it fits on the 
screen, but the changes in the GSR graph are less 
obvious. Try them both and use the one that is most 
helpful to you at the time. 

Changing the sensitivity level does not change the data 
collected, only the way the data are represented on the 
graph. Changing the sensitivity level or recalibrating 
causes the program to regraph old data in terms of the 
new setting to allow new readings to be compared with 
the older data on the graph. 



The Statistics 

The statistics at the bottom of the screen are a numeri- 
cal summary of what is represented on the graph. 
Remember that a high number represents high skin 
resistance and is associated with a low level of tension. 



Current : 
Base: 



Scr Avg: 



Sens : 



the reading currently being plotted. 

the base GSR measurement currently used 

plot the graph. This number changes 

each time you recalibrate. 

average of the newest data plotted. 

This includes all data to the left of 

the moving cursor. 

the current sensitivity setting. 



readings are numbered sequentially 

since the beginning of the session. 
Highest:: the highest reading (lowest tension 

level) detected since the beginning of 

the session. 
Lowest: the lowest reading (highest tension 

level) detected since the beginning of 

the session. 
Span: The difference between the highest 

and lowest readings. 



The Options 

Several options are available while the program is 
running. Hitting the following keys while the program 
is graphing your GSR will have the listed eflfect: 



C: Calibrate 



S: Sensitivity 



Pause 



Q: Quit 



If your readings go off the screen 
recalibration will put them back i 
the center of the Hires graph. Da 
are regraphed in terms of the new 
calibration . 

Sensitvity is retoggled and data 
are regraphed. 

Hit any key while in the Pause mod 
to resume. 

Help Displays these choices at 
bottom of screen. Hit any key to 
resume. 

Quit the session. 



Reading #:the number of the current reading. All 



Theory of Operation 

Getting your skin to talk to your Apple (i.e. measuring 
your GSR) presents a bit of a problem. The first solution 
might appear to use the game controller inputs since 
they measure resistance directly, but the values of a 
typical GSR lay that idea to rest. For example, my GSR 
has varied from about 20K ohms to almost 500K ohms. 
Since the game controllers are capable of measuring 
from to only 150K ohms, many GSR measurements 
will be beyond the reach of the game controller input. 



A better solution is to use the technique described 
earlier: employing a pushbutton input, transfer the 
t (data by varying the rate of "button pushes**. A low GSR 
reading yields closely-spaced "pushes"; higher GSR 
readings come farther apart. The electronics are 
acutally rather simple, so let's delve into the technical 
side of things for a moment. If electronics don*t interest 
you, just skim this next part; you don*t have to under- 
stand every connection to use your biofeedback moni- 
tor. 



The Hardware Interface 

Normally, the PB inputs are at ground level: when they 
aren't pushed, the voltage on their respective pins in the 
game port is 0. When you want to **push the button", 
you connect the PB input to +5 volts. All we have to do 
to register a button push is apply +5 volts to the correct 
pin for the length of time we want the button pushed. 
There doesn't have to be a physical switch present since 
the only important thing is how much voltage the PB 
port sees. 

There are many ways to swing the voltage on the PB 
input pin between and +5 volts. Joysticks and 
paddles use a switch to connect the PB port to the 5 volt 
supply found in the game connector itself. The GSR 
monitor uses a different technique: a type of oscillator 
called an astable multivibrator whose output swings 
between these two voltages at a regular rate of speed. A 
chip called a 555 timer does this Job very well. 

The 555 circuit used to generate this swinging voltage 
includes a resistor and a capacitor, which, together, 
determine the oscillation frequency. The number of 
times per second the 555 timer swings between and 
5 volts is directly proportional to the values of these two 
components. If you build the circuit with a fixed 
capacitor and a fixed resistor, you'll always get the same 
rate of oscillation. If you make either component 
variable, you can vary the output frequency. 

Suppose we use a fixed capacitor, but substitute your 
changing GSR as the resistor portion of the circuit (after 
all, GSRis a resistance). Now when your GSRshifts, the 
circuit sees a changing resistance, and the oscillation 
frequency varies by a proportional amount. 

Since the output of the 555 swings between and 5 
volts, its output can be directly connected to a pushbut- 
ton input in the game port and the game port will be 
fooled into thinking a button is being pushed. So when 
your skin resistance decreases due to sweat, the PB port 
will see an increase in the number of button pushes per 
second. Should your skin resistance rise, the PB port 
will detect fewer pushes per second. Measuring your 
GSR becomes a simple matter of measuring the elapsed 
time between pushes. (See Fig. 6) 



The Machine Language Driver 

The main job of the software portion of our interface (the 
driver) is to measure the time between button pushes. 
Most time-dependent tasks are best dealt with in 
machine language since its faster execution speed 
makes precision easier to achieve. CYCLETIMER is a 
machine language subroutine called from the main 



Applesoft program that does nothing but measure the 
length of time between pushes. 

Looking at this from the game port's point of view, what 
CYCLETIMER will see is a bunch of shifts between and 
5 volts. To make any sense out of this we need to think 
of these voltage changes as cycles. One complete cycle 
consists of a period of time where the voltage is 5 volts 
followed by a period of time where it is volts. 

CYCLETIMER's job is to measure (time) the length of 
one complete cycle. To be consistent, the routine must 
start measuring at the same point in each cycle. 
CYCLETIMER accomplishes this by triggering only on 
the rising edge. In other words, it is sensitive only to the 
transition from to 5 volts. 

One cycle can be defined as the time between sequential 
rising edges, so CYCLETIMERjust finds the first rising 
edge and begins counting the time period, counts 
through the 5 volt portion of the cycle, keeps counting 
when the voltage returns to volts, and finally stops 
counting the instant the voltage begins its rise to 5 volts 
again. 

CYCLETIMER measures (or counts) the length of time 
between each button push by going around in a loop, 
incrementing a counter each pass. When the second 
rising edge is detected, we know the cycle is over, so the 
routine exits, and the the count then reflects the length 
of the cycle. The larger the count, the longer the period 
of the cycle. 

The counter in CYCLETIMER is actually a 3 byte 
number maintained in locations 768, 769 and 770. 
Location 768 ($300) contains the number of ones, while 
769 and 770 hold the number of groups of 256 and 
65536, respectively. 



The Applesoft Program - How It Works 

BIOFEEDBACK is not a long program since its main 
function is just to display data the hardware and 
software interfaces deliver to it. Most of the hard work 
is done by the hardware and CYCLETIMER. The 
subroutine at 990 is the initialization routine. The code 
at 680 performs calibration by taking 100 readings and 
totaling them; the total (TTL) is used in determining how 
to scale the data coming in. The routine at 590 actually 
reads the data collected by the interface. Line 630 
PEEKS the data passed in locations 768-770 into a 
numeric variable. 

Each point plotted on the screen is really an average of 
10 readings to smooth out the potentially jagged-look- 
ing graph. At line 420 is a subroutine that updates all 



the numerical data at the bottom of the screen. 

The main program loop is in lines 150-280. This loop 
calls most of the other subroutines and scales the data. 
The sensitivity levels are represented by the variable 
SENS. If SENS is one. the average of your calibration 
data is put at the center line on the screen, doing no 
scaling at all (a change of one in the data will be reflected 
as a change of one point on the graph). If SENS is zero, 
the program scales the data with the attendant reduc- 
tion in sensitivity. 



Modifications and Improvements 

If you have an unaccelerated Apple 11+ , He or IIc, you 
might want the program to plot readings a little faster 
than it does. Recall that each point plotted on the 
screen is actually ten GSR readings averaged together. 
If we lower the number of readings take in line 610 to 5 
(FOR Y = 1 TO 5) and correct line 66Q to agree with it, 
(GSR = INT (Y/5)), the program will plot readings 
roughly twice as fast. 

The BIOFEEDBACK program presented here could be 
considered unfinished. Many enhancements could be 
added. For example, session data could be saved to 
disk, audio feedback could be added, and other types of 
statistics can be collected and displayed. The whole 
system could be rewritten to support the mouse and use 
a windowing interface. Or... maybe the we need to 
rethink the project in completely new terms! 



Figure 6 - Cycle Time vs. GSR 

Short cycle = low GSR* 
reading = high stress 
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Long cycle = high GSR 
reading = low stress 
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Figure 6 - Cycle Time vs. GSR 

Cycletimer measures the length of one 
complete cycle from rising edge to rising edge. 
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ending here 



Editor: A note about our Applesoft listings - in an ejfort to 
corvuerve space, most of our program listings wiU be 
single column. This means that many lines will wrap, 
particularly in Applesoft programs. We are experiment- 
ing with different layouts, but from our jaundiced view- 
point it appears that indenting wrapped lines is one of 
the best options. Let us know what you think. == -Ross = 



BIOFEEDBACK Program Listing 

100 REM BIOFEEDBflCK 

110 REM 1-11-90 

120 REM [CD 1990 

130 REM BV DRVID GflUGER II 

140 GOSUB 1000: GOSUB 690: GOSUB 960: GOSUB 890 

150 REtt riflIN LOOP 

160 TALLY = 

170 CNTR = 1:TTL = GSR 

180 KEY = PEEK CKBD): IF KEY > 127 THEN 300 

190 GOSUB 600 

200 ARRAY [CNTR) = GSR 

210 IF SENS$ ="HIGH" THEN FUDGE = BASE-80: 

DOTLOC = GSR - FUDGE 
220 IF SENS$ = "LOW" THEN FUDGE = 80 / 

BASE: DOTLOC = GSR * FUDGE 
230 IF DOTLOC < THEN DOTLOC = 
240 IF DOTLOC > 159 THEN DOTLOC = 159 
250 HCOLOR= 0: HPLOT CNTR.0 TO CNTR. 158: 

HCOLOR= 3: HPLOT CNTR. DOTLOC 
260 HCOLOR= 3: HPLOT CNTR + 1 . TO CNTR + 

1. 158 

270 CNTR = CNTR + 1 : IF CNTR = 279 THEN 

HCOLOR= 0: HPLOT CNTR.0 TO CNTR. 158 
:GOTO 170 

280 GOSUB 430: GOTO 180 

290 REM KEYBOARD 

300 POKE STB.0:KEY=KEY-128:KEY$ = CHR$ [KEY] 

310 IF KEYS = "C" THEN GOSUB 690: GOSUB 960: 
GOSUB 790: GOSUB 890: GOTO 180 

320 IF KEYS = "S" THEN IF SENS$ = "HIGH" THEN 
SENS$ = "LOW " : VTAB 24: HTAB IIPRINT 
SENS$; : GOSUB 960: GOSUB 790: GOTO 180 

330 IF KEYS = "S" THEN IF SENSS ="LOW " THEN 
SENSS = "HIGH" : VTAB 24: HTAB 11 : 
PRINT SENSS; : GOSUB 960: GOSUB 790: 
GOTO 180 

340 IF KEYS = "P" THEN HOME : VTAB 22: 

HTAB 1: PRINT" IN PAUSE NODE: HIT ANY 

KEY TO CONTINUE.";: GET A$ : HOME : 

GOSUB 890: GOTO 180 
350 IF KEYS = THEN GOSUB 380: HOME : 

GOSUB 890: GOTO 180 
360 IF KEYS = "Q" THEN HOME : VTAB 22: HTAB 

5: PRINT "SURE YOU WANT TO QUIT? [Y/ND"; 

:GET AS: IF AS = "Y" THEN TEXT : HOME 

: END 

370 GOSUB 890: GOTO 180 
380 HOME : VTAB 21: HTAB 1 
390 HTAB 5: PRINT "S = TOGGLE SENS. C = 
CALIBRATE" 

400 HTAB 5: PRINT "P = PAUSE Q = QUIT" 

410 VTAB 24: HTAB 5: PRINT "HIT ANY KEY TO 
CONTINUE...";: GET AS: RETURN 
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420 
430 
440 
450 
460 
470 
480 
490 
500 
510 
520 
530 
540 
550 
560 
570 
580 
590 
600 
610 
620 



REM UPDATE STRTISTICS 
VTflB 21: HTflB 11: PRINT 
: ' HTflB 1 1 
TALLY + 
HTAB 31 
HTAB 11 
HTAB 



11 



VTAB 21 
TALLV = 
VTAB 21 
VTAB 22 
VTAB 22 
IF GSR > 
VTAB 22: 

VTAB 23: HTAB 11 
VTAB 23: 
VTAB 23: 
IF GSR < 
VTAB 23 



: PRINT GSR 
1:TTL = TTL + GSR 
PRINT TALLY 
PRINT " 
PRINT BASE 
HIGHEST THEN HIGHEST = GSR 
HTAB 31 : PRINT HIGHEST 
PRINT " 

PRINT INT CTTL / CNTR) 
PRINT " 



HTAB 11 
HTAB 31 

LOWEST THEN LOWEST = GSR 



HTAB 31 
HTAB 11 
HTAB 31 



VTAB 24 
VTAB 24 
RETURN 

REM GET A GSR READING 
Y = 
FOR X = 1 TO 10 
CALL 771 



PRINT LOWEST 
PRINT SENS$; 
PRINT HIGHEST - LOWEST; 



2 + PEEK [763} * 



630 GSR = PEEK [770 ) * 256 

256 + PEEK [7683 
640 Y = Y + GSR 
650 NEXT X 

660 GSR = INT [Y / 10) 

670 RETURN 

680 REM CALIBRATE 

630 HOME :TL = 0: VTAB 2: HTAB 14: INVERSE : 
PRINT "BIOFEEDBACK": NORMAL : VTAB 5: 
HTAB 11 :PRINT "BY DAVID GAUGER II" 



700 



710 



720 



730 



VTAB 10: HTAB 4: PRINT 
KEY IS DOWN. 3" 

VTAB 22: HTAB 1 : PRINT 
BEGIN CALIBRATION. . . 

HOME : VTAB 23: HTAB 15 



[BE SURE CAPS LOCK 

HIT ANY KEY TO 
" ; : GET A$ 
FLASH : PRINT 



"CALIBRATING" 
FOR Z = 1 TO 10 



NORMAL 



740 
750 
760 
770 
780 
790 
800 
810 
820 
830 

840 



850 
860 
870 
880 
890 
900 

910 

920 

930 

940 

950 

960 

970 

980 

990 

1000 

1010 

1020 
1030 



10D 



GOSUB 600 :TL = TL + GSR 
NEXT Z 

BASE = INT CTL / 
RETURN 

REM REDRAW DATA 

X = 

X = X + 1 

IF X > 279 THEN RETURN 

IF ARRAY [XD = THEN RETURN 

IF SENS$ = "HIGH" THEN DOTLOC 

[BASE - 80) 
IF SENS$ = "LOW " THEN DOTLOC 

[80 / BASE) 



IF DOTLOC > 158 THEN DOTLOC = 
IF DOTLOC < THEN DOTLOC = 
HPLOT X. DOTLOC: GOTO 800 
REM INIT STATISTICS DISPLAY 
HOME 

1: PRINT 
"READING 
1: PRINT 



ARRAY [X) - 
ARRAY [X) * 



158 



: HTAB 
PRINT 
: HTAB 
PRINT "HIGHEST 



"CURRENT 
« = ••; 
"BASE 



HTAB 



HTAB 



HTAB 



HTAB 



VTAB 21 

19: 
VTflB 22 
19: 

VTflB 23: HTflB 1: PRINT "SCR flVG = 

19: PRINT "LOWEST = "; 
VTflB 24: HTflB 1: PRINT "SENS 

19: PRINT "SPflN = "; 

RETURN 

REM SETUP HIRES SCREEN 

HGR : HCOLOR= 3 

HPLOT 0.0 TO 0.159 TO 279,159 

RETURN 

REM INIT 

SENS$ = "LOW " : DIM flRRflY[279) 
LOWEST = 10000: HIGHEST = : KBD = 49152: STB 
= 49168 

PRINT CHR$ [4)"BL0flD CYCLETIMER . OBJ" 
RETURN 



Cycletimer Listing 



0303: R9 00 



1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 



* CYCLETIMER 

* by David Gauger 1 1 

* CC) 1989 

* Merlin 8 Assembler 






org 


$303 




loiu 




$300 


;ones passed to BRSIC here 


med 




$301 


; groups of 256 passed here 


h i gh 




$302 


; groups of 65536 passed here 


bttn 




$C063 


; address of pushbutton #3 


start 


Ida 


#00 


; in i t counters 



0305 


8D 


00 


03 


21 




sta 


1 OUi 




0308 


8D 


01 


03 


22 




sta 


med 




030B: 


8D 


02 


03 


23 




sta 


high 




030E 


2C 


63 


C0 


24 


uiaveh i 


bit 


bttn 


; positive 1/2 of cycle? 


0311 


30 


FB 




25 




bm i 


uiaveh i 


;yes: loop until negative 


0313 


2C 


63 


C0 


26 


Luavel o 


bit 


bttn 


; negative 1/2 of cycle? 


0316 


10 


FB 




27 




bpl 


uiavel o 


;yes: wait for 1st rising edge 


0318 


20 


29 


03 


28 


posjsr 


update 


; update counters [positive half) 


031B 


2C 


63 


C0 


29 




bit 


bttn 


; st i 1 1 positive 1/2 of cycle? 


031E 


30 


F8 




30 




bflii 


pos 


; yes ~ keep count i ng 


0320 


20 


29 


03 


31 




jsr 


update 


; no : neg noui^ but keep counting 


0323 


2C 


63 


C0 


32 




bit 


bttn 


; st i 1 1 negative 1/2 of cycle? 


0326 


10 


F8 




33 




bpl 


neg 


; yes - keep count i ng 


0328 


60 


34 
35 






dun 


rts 




;no: found 2nd rising edge. 


0329 


EE 


00 


03 


36 


update 


i nc 


1 GUI 


; update counters here 


032C 


F0 


03 




37 




beq 


nextl 


; if rolled over, inc 256*8 [med) 


032E 


4C 


3C 


03 


38 




jmp 


done 


; otherwise just rts 


0331 


EE 


01 


03 


39 


nextl 


i nc 


med 


;next 256 


0334 


F0 


03 




40 




beq 


next2 


; if rolled over, inc 65536 'S 


0336 


4C 


3C 


03 


41 




jmp 


done 


.otherwise rts 


0339 


EE 


02 


03 


42 


next2 


i nc 


h i gh 


;next 65536 


033C 


60 


43 






done 


rts 




; don't worry for 65536 rollover 



I'm aivin' her all she's got Captain! ^ »> ^' = ^ 

A TransWarp GS CDEV^^^ 

by Herb Hrowal 



With the advent of System Disk 5.0, a new method of 
modifying the settings of the Apple Ilgs is available, 
through the Control Panel NDA, Unlike the text-based 
control panel (accessed from the CDA menu), the NDA 
is much more flexible in that it is easily expanded with 
additional CDEVs (Control panel DEVices). 

E>ery time the Control Panel NDA is selected from the 
apple menu of a desktop application, it scans the */ 
SYSTEM/CDEVS folder of the boot device searching for 
all files with a type of $C7/$0(X)0. Each CDEV found is 
recorded by the NDA in a separate file (VSYSTEM/ 
CDEVS/CDEV.DATA) . The icon and title for each CDEV 
is displayed in the NDA window, and can be clicked on 
to activate the corresponding CDEV. 

The purpose of this article is to show how you can create 
your own CDEV with very little effort. CDEVs are not 
restricted to modifying the system settings — some other 
uses for them might be a screen saver, or to control a 
piece of hardware in your computer. In this article. I will 
show how to write a CDEV to control the popular 



TransWarp GS accelerator card. 

Let's take a look at the Rez source file (listing one) first. 

Each CDEV is required to include three resource types, 
in a predetermined order, with an ID of 1. The first 
resource in the file must be a standard icon resource, 
type $800 1 . This is the icon that will be displayed in the 
NDA window. If the CDEV has an initialization routine 
(discussed later), the icon will also be displayed on the 
bottom left comer of the screen at boot time. One thing 
to be aware of with the icon is that it must have a height 
of 20 and a width of 28 in order to be displayed properly 
during boot up. The reason for this is that the GS/OS 
boot code does not use the size information supplied 
with your icon, but is hard coded for an icon that is 20 
X 28. If you don't have an initialization routine, the icon 
can be any legal size. 

Here's what the icon resource looks like in Rez code: 
/* resource type $8001, ID = 1 */ 



resource ricon CO { 
Cicon flags), 
(icon height], 
Cicon width), 
Cicon data), 
Cmask data), 
); 

The second required resource is the actual program 
code that does the work for the CDEV. The CDEV code 
resource (type $8018) is simply your application, 
turned into a CODE resource and inserted into the 
CDEV resource fork. This resource is then loaded and 
called when the CDEVs icon is selected in the NDA. The 
maximum size of the CDEV code resource is 64K. which 
is more than enough for most applications. 

The command (in the Rez source code) to do this is: 

read rCDEVCode Cl. convert) ^tui.code^; 

The third and final required resource is the CDEV flags 
resource (type $8019). This resource tells the Control 
Panel NDA what types of events the CDEV can handle 
and also contains the data rectangle, the title, the 
author, and the version of the CDEV. Again, the Rez 
code you need to have looks like this: 

resource rCDEVFlags CO C 
flags, 
enabl ed, 
vers i on, 
machine, 
reserved, 
data rectangle, 
title, 
author, 
version name, 

}; 

Let*s start at the bottom of these flags and work our way 
up. 

**Version Name** is an 8 character string that is dis- 
played in the upper right hand comer of the Help /About 
box that is created every time the user clicks on the Help 
button. 

"Author** is a 32 character string containing the name 
of the author of the CDEV. This is also displayed in the 
Help /About box. 

Title** is a 15 character string containing the name of 
the CDEV. This is displayed with the icon in the NDA*s 
scrollable window and in the Help/About box. 



"Data Rectangle** is four words (a standard RECT) 
containing the size of the window the CDEV needs to 
work in. The top left comer must be 0.0. 

"Machine** is a one hyte field containing the minimum 
ROM version needed for the CDEV to run. For example, 
this could be useful when writing a CDEV that needs a 
ROM 03 GS to run. 

"Version" is a one byte field containing the version 
number of the CDEV. 

"Enabled** is a one byte field used to determined whether 
the CDEV can be activated or not. When this byte is 
zero, the CDEV can*t be used. 



"Flags** is a one word field containing flags used to 
enable the type of events the CDEV wants to receive. The 
flag definitions are: 



Bit 


Name 


Enabled Event 


15 thru 


11 


Reserved, must be zero 


10 


wantRun 


RunCDEV 


9 


uiantH i t 


HitCDEV 


8 


wantRect 


RectCDEV 


7 


wantflbout 


flboutCDEV 


6 


uiantCreate 


1 CreateCDEV 


5 


wantEvent 


EventCDEV 


4 


luantCI ose 


CloseCDEV 


3 


uiantln i t 


InitCDEV 


2 


Reserved, 


must be zero 


1 


uiantBoot 


BootCDEV 





Reserved, 


must be zero 



Following the 3 required resources, any number of 
additional resources maybe used in any order you like. 
(The rest of the Rez code, in this case, is templates for 
the help/about screen, the menus, and the controls 
used in the TWOS CDEV.) All controls in the window 
must be 'super controls* created with _NewControl2, 
since the Control Panel NDA uses _TaskMasterDA to 
track them. For 

more information on the format of CDEVs. refer to Apple 
II File Type Note $C7 (September 1989). 

Now that we have the Rez portion out of the way, we can 
take a look at the actual code to control the CDEV. I 
wrote this code (listing two) in assembly language with 
Merlin 16+, but have also written CDEVs in C. and they 
can be done in Pascal as well. 

Whenever an event occurs in your window, the CDEV 
Code resource is called •*tool-style" by the Control Panel 
NDA. This means it pushes parameters on the stack 
and calls the CDEV similar to the way you make a 
toolbox call. It is the CDEVs responsibility to extract the 



mm 



parameters from the stack and fix the stack pointer 
before it retums control back to the NDA. The parame- 
ters passed are: 

Long Result 

Word Message 

Long Datal 

Long Data2 

3 bytes RTL Rddress 

There are 1 1 possible values for Message. Currently, 
message three is reserved for future use as a shutdown 
message. I also tried using MachineCDEV (explained 
after the table) to enable or disable the CDEV depending 
on whether or not a TransWarp GS was installed, but it 
didn't seem to work, so I abandoned the idea. 

Here's a table of each message, and the associated data 
passed with them: 



Message 


Datal 


Data2 


Result 


1 - 


MachineCDEV 


undef 


undef 


= i nact i ve 


2 - 


BootCDEV 


undef 


undef 


undef 


3 - 


Reserved 


undef 


undef 


undef 


4 - 


InitCDEV 


wnd ptr 


undef 


undef 


5 - 


CloseCDEV 


undef 


undef 


undef 


§ - 


EventsCDEV 


evntrec ptr 


undef 


undef 


7 - 


CreateCDEV 


uind ptr 


undef 


undef 


8 - 


RboutCDEV 


wnd ptr 


undef 


undef 


9 - 


RectCDEV 


rect ptr 


undef 


undef 


10 - 


■ HitCDEV 


Ctrl hndl 


Ctrl ID 


undef 


11 - 


- RunCDEV 


undef 


undef 


undef 



MachineCDEV is called when the NDA is activated. This 
is an ideal place to determine if the CDEV should be 
displayed or not. If zero is retumed in Result, the icon 
is not displayed. Currently it is not possible to enable 
MachineCDEV. but should be available in the future. 

BootCDEV is called at boot time and should contain the 
code to initialize the peripheral you are controlling (if 
necessary). The icon for the CDEV will be displayed on 
the bottom right of the screen for the duration of the 
initialization routine. 

InitCDEV is called after CreateCDEV. but before the 
controls are displayed. This is where you should initial- 
ize all the controls in the window. 

CloseCDEV is called when the NDA window is closed or 
another CDEV is selected. Housekeeping should be 
taken care of in this routine. 

E^ventsCDEV is called before the event record is passed 
to TaskMasterDA, allowing you to intercept or even 
change the event record before processing (if desired). 

CreateCDEV is called when CDEV is selected. This is 



where the controls should be created. Initialization of 
the controls should be done in InitCDEV. 

AboutCDEV is called when the user clicks on the Help 
button on the bottom of the NDA window. 

RectCDEV is called before the window is displayed and 
is used to change the 

size of your display window if it needs resizing. 

HitCDEV is called every time one of your controls in the 
window is clicked on or "hit". 

RunCDEV is called 60 times per second and is an ideal 
place to update a clock display, poll disk devices for a 
certain volume, or just to make sure the controls don't 
need updating. 

The first thing we need to do when the code is called is 
set the bank register (since we don't know where we'll be 
in memory), get the parameters off the stack, fix the 
stack pointer, and call the proper routine. When the 
routine retums, we reset the old bank and retum 
control back to the Control Panel NDA (lines 46-77). 

Every time the machine is booted up, the BootCDEV 
routine is called (lines 106- 115). The loop is used to 
delay the boot process for about one second so the icon 
will stay on the screen a little longer than it normally 
would (this delay is not necessary and may be discarded 
if you so desire). When the delay is complete, we call a 
routine that verifies the existence of a TransWarp GS 
(line 1 10) and, if so, sets the speed to maximum (lines 
111-115). 

As soon as our icon is clicked on in the Control Panel 
NDA, a window is created with the size information we 
passed the NDA in the Rez source. The NDA then 
proceeds to call the CreateCDEV routine (lines 144-173) 
which again checks for the existence of a TransWarp 
GS. If the card is found, we use the window pointer 
passed to us by the NDA to create all the controls in the 
window (lines 161-173). If no card was found, a static 
text control is created that wUl notify the user of the 
card's absence (lines 151-158). The controls are not 
actually drawn until after the NDA calls InitCDEV. 

InitCDEV retrieves the handles (lines 235-251) to the 
three controls that might be altered (for use by the 
SetControls routine), sets up the version number and 
maximum speed static text controls (lines 253-275). 
and calls SetControls to initialize the remaining con- 
trols. After all controls have been initialized and control 
is retumed to the Control Panel NDA, it makes the 
controls visible and draws them. 

At this time, the user can select an option from one of the 
pop-up menus. When one of the menus is "hit" (either by 
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clicking in it with the mouse or pressing the appropriate 
key equivalents) the Control Panel NDA calls our 
HitCDEV routine, passing to it the ID and the handle to 
the control. The first thing we do is verify that one of the 
menus was selected (lines 286-290) and, if so, call one 
of two routines (lines 291-294). 

If the speed menu was selected, the SetSpeed routine 
determines which item was hit (lines 306-310), loads 
the speed index (lines 312-317), calls the TransWarp 
ROM routine SetCurlSpeed (lineS 18), and calls SetCon- 
trols to update the current speed static text control. 
Altemately, the SetlRQ routine follows the same proc- 
ess to determine if it should enable or disable the IRQ 
logic (lines 331-346). These routines aren*t necessary 
for all CDEVs, but are required for the operation of the 
TransWarp CDEV. 

SetControls determines if any of the operating parame- 
ters have changed since the last time through. First it 
retrieves the conflguratlon word from the card and saves 
it (lines 392-394) and checks if the IRQ status has 
changed (lines 395-401). If the status has changed, it 
saves the new information, updates the IRQ menu, and 
redraws it (lines 402-409). The next step is to get the 
current speed index (line 412). Since future versions of 
the card might have more than three indices (0, 1,& 2) we 
ensure that the index is not greater than two (lines 413- 
415). 

The reason for the code segment at lines 4 1 6-42 1 is that 
older versions of the TransWarp ROM retumed a one 
here whether the card was running at fast or TransWarp 
speed. All that's done is if a one is retumed as the index 
and the TransWarp flag is set in the configuration word, 
the index is made a two, else nothing is touched. Again, 
if the index has changed, the new value is saved, the 
speed menu is updated, and then redrawn (lines 428- 
435). The final task of SetControls is to determine 
whether the speed has changed or not. This segment 
works almost the same as setting the speed index except 
it uses the numeric speed retumed by GetCurSpeed, 
instead of the speed index. If the retumed value is 2600 
and the TW flag is set, we make the speed 7000 (the 
TransWarp GS retums it's operating speed in kilohertz, 
so we convert the number to megahertz for displaying). 

The RunCDEV routine (line 354) simply verifies that you 
have a TransWarp installed and, if so, calls SetControls 
(line 357) to determine if any operating parameters for 
the TransWarp have changed. This routine isn't neces- 
sary, but will automatically update the screen if you 
change the speed or IRQ setting from the TransWarp GS 
CDA. 

The AboutCDEV routine creates a static text control in 
the window created by the NDA. The icon, CDEV name. 



author, version number, and OK button are automati- 
cally placed in the window by the Control Panel NDA, 
making life much easier on the programmer. I simply 
give a very brief description on what the CDEV does and 
display the key equivalents for the speed menu. 

To put the entire CDEV together, follow these steps: 
enter the assembly source code (listing two) and type 
OA-6 to assemble and link it. If the assembly and link 
completed successfully, enter the Rez code (listing one) 
and the APW/ORCA command file (listing three) and 
execute it. The Rez code reads the control code and 
includes it in the CDEV. When the compile is done, the 
CDEV is automatically copied to the proper folder for 
testing. Select the Control Panel NDA from any desktop 
application, click on the TransWarp icon, and away you 
go. 



Listing 1 - TransWarp GS CDev Rez Code 

« include "types. rez" 

resource ricon CD C 

0x8000. /* color icon */ 

H0. Height */ 

28, /* Width */ 

/* image data 

$"FFFFFFFFFFFFFFFFFFFFFFFFFFFF" 
$"F11111F1FFFFF1F11111F11111FF" 
$"FFF1FFF1 IFFFl IFIFFFFFIFFFFFF" 
$"FFF1FFFF1F1F1FF1FF11F11111FF" 
$ " FFF 1 FFFF 1 1 1 1 1 FF 1 FFF 1 FFFFF 1 FF " 
$"FFF1FFFF11F11FF11111F11111FF" 
$ "FFFFFFFFFFFFFFFFFFFFFFFFFFFF " 
$"FFFFFFFFF0000000000FFFFFFFFF" 
$"FFFFFFFFF0EEEEEEEE0FFFFFFFFF" 
$"FFFFFFFFF0EEEEEEEE0FFFFFFFFF" 
$"FFFFFFFFF0EEEEEEEE0FFFFFFFFF" 
$"FFFFFFFFF0000000000FFFFFFFFF" 
$"FFFFFFFF0DDDDDDDDDD0FFFFFFFF" 
$"FFFFFFF0DODDDDDDDDDD0FFFFFFF" 
$"FFFFFFF00000000000000FFFFFFF" 
$ "FFFFFFFFFFFFFFFFFFFFFFFFFFFF" 
$"FFFF4444444444444FFFFFFFFFFF" 
$"FFFFFFFFFFFFFFF444444444444F" 
$"F444444444444FFFFFFFFFFFFFFF" 
$ " FFFFFFFFFFF4444444444444FFFF " , 

/* mask data */ 

$"0000000000000000000000000000" 
$"0FFFFF0F00000F0FFFFF0FFFFF00" 
$"000F000FF000FF0F00000F000000" 
$ '•000F0000F0F0F00F00FF0FFFFF00 " 
$"000F0000FFFFF00F000F00000F00" 
$"000F0000FF0FF00FFFFF0FFFFF00" 
$"0000000000000000000000000000" 
$"000000000FFFFFFFFFF000000000" 



>; 



$"000000000FFFFFFFFFF000000000" 
$"000000000FFFFFFFFFF000C000C0" 
$"000000000FFFFFFFFFF000000000" 
$"000000000FFFFFFFFFF000000000" 
$"00000000FFFFFFFFFFFFC0000000" 
$"0000000FFFFFFFFFFFFFF0000000" 
$"0000000FFFFFFFFFFFFFF0000000" 

$** 0000000000000000000000000000 " 

$"0000FFFFFFFFFFFFF00000000000" 
$ - 000000000000000FFFFFFFFFFFF0 " 
$"0FFFFFFFFFFFF000000000000000" 
$ " 00000000000FFFFFFFFFFFFF0000 " 



read rCDEVCode Cl^ convert) "tui.code" 
/* Include the program */ 

resource rCDEVFIags Cl) { 

/* required flags 

for al 1 CDevs */ 

uiantflbout + luantCreate 

+ uiantBoot + uiantRun^ 

1. /* enabled 

15, version 
1, /* machine 

0, /* reserved 

C0. 0. 85. 200). /* rect 



+ uiantHit + wantlnit 



0. 85. 200). 
" TransWarp". /* name [15 chars, max]*/ 
"Herb Hrowal & Palace Productions^, 
/* Author [32 chars. max) */ 

"vl.5" /* Ver name [8 chars, max) */ 



» 



resource rTextForLETextBox2 [HelpText) ( 

"The TransUarp CDEV allows you to change the" 
"settings of the TransWarp QS. Speed fldj . " 
"sets the system" 

" speed to normal, fast, or TransWarp. " 
"flppletalk" 

" IRQ enables or disables AT interrupts." 

TBEndOf L i ne 

TBEndOf L i ne 

"S$11N = Normal Speed" 

TBEndOf L i ne 

"N$11F = Fast Speed" 

TBEndOf L i ne 

"\$11T = TransWarp Speed" 

); 



[SpeedMenu) ( 

/* control ID "^Z 
/* cor>trol rect 
/* control type */ 
/* flags */ 



resource rControl Tempi ate 
SpeedMenu. 
{S3. 10.35. 190). 
PopUpControl CC 
fTypeEPopUp, 

Fct 1 Pr ocNotPtr+Fct 1 WantsEven ts+Ref I sResour ce , 
/* MoreFlags */ 

0, /* RefCon */ 

0. Title Width */ 

SpeedMenu. /* Menu ref */ 

SpeedMenuIteml /* Initial Value */ 

)) 



/* "equates" for file */ 

«def ine Help $1 

«def ine NotFound $2 

•define SpeedMenu $3 

•define IRQMenu $4 

•define HelpText $1001 

•define NotFoundText $2001 

•define SpeedMenuIteml $3001 

•define SpeedMenuItem2 $3002 

•define SpeedMenuItem3 $3003 

•define IRQMenuIteml $4001 

•define IRQMenu I tem2 $4002 



resource rControl List [1) ( 
( 

SpeedMenu, 

IRQMenu 

> 



resource rControl Tempi ate [Help) ( 
Help. 

(35,5. 130.290). 
statTextControl (( 
NIL. 

f Ct 1 ProcNotPtr+Ref IsResource, 
NIL. 

HelpText, 
Help 



resource rMenu [SpeedMenu) ( 
SpeedMenu. /* id of menu */ 

Ref IsResource * MenuT i tl eRef Sh i f t + Ref IsRe- 
source *ItemRefShift + f fll 1 owCache, 
SpeedMenu, /* id oft i tie string V 

( SpeedMenuIteml , SpeedMenuItem2. SpeedMenuItem3 
); /* id's of items */ 
); 

resource rPString [SpeedMenu) C 
^ "Speed fldJ : 

resource rMenuItem [SpeedMenuIteml) { 
SpeedMenuIteml , 

"N","n", /* key equivalents */ 

0. 

Ref I sResour ce* I temT i 1 1 eRef Sh i f t+f XOR , 
SpeedMenuIteml 
) * 

resource rPString [SpeedMenuIteml) ( 
"Normal" 

); 



resource rMenuItem [SpeedMenu I tem2) 

SpeedMenu I tem2, 
equivalents 

"F"."f", 

0. 



/* key 



Ref IsResource*! temT I tl eRef Sh i f t+f XOR, 
SpeedMenuItemE 



resource rPString CSpeedl1enuItein2] ( 

"Fast" 
}; 



resource rMenuItefn CSpeedttenuItemSD { 
Speedhenu I tem3 , 

"T'\"t", /* key 

equivalents */ 
0. 

Ref I sResource* I temT 1 1 1 eRef Sh i f t+f XOR+f I ta 1 i c , 
Speedhenu Items 

}; 

resource rPString CSpeedMenuItemSD ( 
^ "TransUarp" 

resource rControl Tempi ate ClRQMenuD ( 
IRQMenu, control ID */ 

(40,10,52,130), /♦ control rectangle */ 

PopUpControl C( control type */ 

fType2PopUp, /* flags */ 

FctlProcNotPtr+Ref IsResource,/* MoreFlags */ 
0, /* Ref Con */ 

0, /* Title Width 

IRQMenu, /* Menu ref 

IRQMenuIteml Initial Value ♦/ 

» 



0. 

Ref IsResource*I temT i 1 1 eRef Sh i f t+f XOR, 
IRQMenu I tem2 



}; 



resource rPString [IRQrienuItemS] C 

"Off 
); 



resource rControl Temp late CNotFound) ( 
NotFound, 
G0, 20, 35, 180}, 
statTextControl CC 
NIL, 

fC 1 1 Procl\lotPtr+Ref IsResource , 

NIL, 

NotFoundText, 
NotFound 

)) 



resource rTextForLETextBox2 [NotFoundText) { 
"TWGS Not Instal led.Nn" 

}; 



resource rMenu ClRQUenu] ( 
IRQMenu, /* i d of menu */ 

Ref IsResource * MenuT i t 1 eRef Sh i f t + Ref IsRe- 
source *ItemRefShift + f Rl 1 oiuCache, 
IRQMenu, /* id of title string */ 
( IRQMenuIteml, IRQMenuItem2 );/* id;s of items 

}; 

resource rPString CiRQMenuD ( 

"flppleTalk IRQ: 
); 



resource rMenuItem [IRQMenuIteml D ( 
IRQMenuIteml, 

0. ' 

Ref IsResource^ItemT i 1 1 eRef Sh i f t+f XOR+f Ital i c, 
IRQMenuIteml 



resource rPString [IRQMenuIteml J ( 

"On" 
}; 



resource rMenuItem [IRQMenuItem2) ( 
IRQMenuItem2, 
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Listing 2 - TransUarp CDEV Source Code 



1 1 St off 

2 xc 

3 xc 

4 mx 

5 typ exe 

6 use tui.macs ; include macro file 

7 rel ;make relocatable 

8 dsk tui . code . 1 ; assemb 1 e to d i sk 
S 

10 *===========.===============================:===:====== 

11* * 

12 * Control code for the TransWarp COev * 

13 * * 

14 * Copyright Co) 1990 * 

15 * Herb Hrouial, Palace Productions * 

16 * and Ariel Publishing * 

17 >♦< >♦< 

18 *========================================* 

19 

20 * ^* 

21 * 

22 * Equates: 

23 * 
24 



25 CtlProcRefNotPtr = $1000 

;more flag for extended controls 

26 TitlelsPtr = 

;more flag for extended controls 

27 

28 TransWarp ID = $BCFF00 

.•location of ID. (TUGS) 

29 GetTWInfo = $BCFF08 

; returns with fl = features. X = ver 

30 GetnaxSpeed = $BCFF10 .obvious 

31 Freq2Index = $BCFF18 

.converts the numerical speed to index 

32 GetCurSpeed = $BCFF20 .obvious 

33 GetCurlSpeed = $BCFF28 

.•returns the current speed index 

34 SetCurlSpeed = $BCFF2C 

.-sets the speed with the index 

35 DisablelRQLogic = $BCFF34 

.kills IRQ interrupts 

36 EnablelRQLogic = $BCFF38 

.enables IRQ interrupts 

37 GetTUConf Ig = $BCFF3C 

; returns info about the card 

38 

39 

40 * ^ 

41 * 

42 * This is the routine called every time 

43 * an event occurs in my window 

44 * 
45 

46 Start 

47 phb 

48 phk 

49 p 1 b ; 1 et • s run i n my bank 
50 

51 Ida 5.S 

;get all the pertinent data 

52 sta Data2 

53 Ida 7.S 



54 sta Data2+2 

55 Ida 9.S 

56 sta Datal 

57 Ida 11. s 

58 sta Datal+2 

59 Ida 13. s 

60 sta Hessage 

61 Ida l.s ; move RTL address and bnk 

62 sta 1 1 . s 

63 Ida 3.S 

64 sta 13. s 

65 tsc 

66 clc 

67 ado «10 ;f ix the stack pointer 

68 tcs 
69 

70 1 da Message 

71 dec 

72 asl 

73 tax 

74 Jsr [Routines.x) ;do what NDfl wants 
75 

75 plb ; get original bank 
77 rtl .and return 

78 
79 

80 Routines da Dummy jMachineCDev 

81 da BootCDev 

82 da Dummy ; Reserved 

83 da InitCDev 

84 da Dummy jCloseCDev 

85 da Dummy .EventsCDev 

86 da CreateCDev 

87 da flboutCDev 

88 da Dummy ;RectCDev 

89 da HitCDev 

90 da RunCDev 

91 

92 * 
93 

94 Dummy rts 

95 

96 * * 

97 * 



98 * This called only at bootup . It displays 

99 * icon for CDev and anything else necessary 

100 * for the CDev to run. Here making it delay 

101 * the boot so icon will be displayed longer. 

102 * It also sets the TWGS speed to max. 

103 * 
104 

105 BootCDev 



106 Idy 4120000 ;my delay 

107 ]Loop dey 

108 bne ]Loop 
109 

110 Jsr F i ndTransWarp 
;go find the transwarp 

111 Ida TWFlag 

112 beq :NoTW 

113 Jsl SetCurlSpeed 
;set speed with index from Find 

114 

115 :NoTW rts 
116 

117 * * 



1 1 Q 


m 






1 HA 
1 f'f 






1 1 Q 




This rtn called every 


t ime user cl icks 


1 rO 






lev 




on Help bin. The title, author, & version 




1 ex V 1 L 1 S V 


; v-ne s va v i c vex v convro i i i s v- 


1 P 1 
IC 1 




« defined in REZ portion of the source. 


iff 


our 1 






>»( 






1 "70 
1 ro 


aur 1 


^uropcj^ V 1 










179 
X r o 


adr 1 


MaxSndCt 1 


1 P4 
ICH 


RboutCDev 




X O V 




V , vr lU v t 1 1 d V 


IPS 




PushLong «0 


; space for result 


181 






1 PR 




PushLong Datal 


; tu i ndoui po i nter 


1 fiP 






127 




PushWord «2 




183 


VersCtl dw 


8 ; parm count 






; the control is a resource 


184 


adrl 


5 ctl ID 


128 




PushLong «1 


; it is ID «1 


185 


dui 


8,25,20,190 ; bounds rect 


1 p<) 




_WeujControl2 


;and cal 1 it 


1 fl6 
X o\j 


our 1 


$81000000 - <;tp)t txt control 






pla 




1 87 
X o r 


Hill 


f 1.305 






; remove excess baggage 


1 oo 


diu 


v« V 1 r r V/^nc: 1 JVvi V»r vf 1 1 v 1 ^ X vf 


lO 1 




pla 






, iiivr xzt 1 <i^]> 




1 Q9 

loc 




rts 




loo 


aar i 


; ref con 






;and get outta here 




1 9fl 
XOv 






loo 








lol 


GUI 


1 r ; 1 eng oi vex v 


1 '54 
1 ot 


* 




* 


1 9P 
X oc 






loo 








1 OO 


ri i»^Qr>«Hr+- 1 Hill 

LfUropoL/ V 1 uw 


O ^ poi In wUl»4nv 


135 




This calls rtn to ck 


if TWGS is instal led 


194 


adrl 


5 ;ctl ID 


137 




If it is, the control s are created in the 


195 


dui 


57,10,59,200 ; bounds rect 


138 


* 


ui i ndouj . If no TUGS ex i sts then a msg f or 


195 


adrl 


$81000000 • ^tat txt control 


1 1^ 

1 O'^ 


>♦< 


this cond i t i on is thrown in the window. 


1 <57 

X O r 




\ • "T 1 ^c\<: 

Ctil ProcRef NotPtr+T i tlelsPtr 

w VII 1 w wi 1 1 V w VI VI livi ^ A ^ 1 VI 


140 


>♦« 


[the Mach i nceCDev rtn 


shoul d be used but 


198 


dw 


141 

X ^ X 


>t( 


is not yet supported 


by Cntrl Panel NDflD . 








142 


>*( 






199 


adrl 


; ref con 


143 








200 


adrl 


Cur*SndText • texti^ef 

wVII WL/VJ 1 Vii^ V , VC^ VI C 1 


144 


CreateCDev 




201 


dw 


28 lenoth of text 

Im W / 1 ^ 1 1 ^ VII W 1 V ^ r\ V 


145 




j sr F i ndTransUlarp 


202 










; go f i nd the transuiarp 


203 


MaxSndCtl dw 


8 • Darm count 

, fJHSI III W WAwl 1 V 


146 




Ida TWFlag 




204 


adrl 


7 ;ctl ID 






; t et ' s us knouj i f uie 


f ound i t 


cvo 


dw 


70 1 80 P00 • Knijnd< r'tar^'h 

IV, XV, QV, ^%Jv , LJv^VirivJS> 1 W V 


147 

X ^ f 




bne : Ok 




P06 


adrl 


$81000000 • <:"fcat txt contnol 






;yup, we did 




PCJ7 


d w 


flao^ 


148 






208 


dw 


Ct 1 ProcRef NotPtr+T i 1 1 elsPtr 


X TO 


>«< 


card not found so tell user and leave. 




, lllv^r xzt 1 o^l> 




150 








209 


adrl 


• r-oT onr\ 

W , 1 ^ 1 v W 1 1 


151 




PushLong «0 


; space 


210 


adrl 


M^v^ndTcivt" • "t" vt" <3 "T 

1 la^O|JVJ 1 V , VC^ Vl C 1 


152 




PushLong Datal 


;wnd ptr 


211 


dw 


26 • 1 enoth of text 

Ib \0 , 1 1 1 \f VII W 1 V ^ ^ V 


153 




PushWord «2 


; ref erence a rsrc 


212 






154 




PushLong «2 


; resource ID 


213 


Y v^l 1 V <u ^ w 


1 1 cii i^r^Qi viw V 


155 




_l\lewContro 1 2 


; create i t 


214 




' X . X ' , 00 


156 




pla 




215 






157 




pla 


; remove the garbage 


216 


CurSpdText asc 


'Current Speed = ' 
'XX. XX Mhz. ',00 


158 




rts 


;and get outta here 


217 


CurSpeed asc 


159 








218 






160 








219 


MaxSpdText asc 


'Maximum Speed = ' 


1 B1 

X V X 


:0k PushLong «»0 




ppo 


MaxSpeed asc 


'XX. XX Mhz. ',00 


162 




PushLong Datal 




221 






X vio 




PushWord «9 




ppp 


>♦« 








; ref erence a 1 i st of 


resources 


lUCO 


>♦< 




1 R4 




PushLong «1 


;ID of 1 ist 


PP4 


* In it all controls that need it and 


X s/O 




_!MewControl 2 




PPS 


* get hndls to 


cntrls that might be changed 


166 








2Z6 


* throughout the program . 


167 




PushLong Datal 




227 


♦ 




168 




PushWord «3 




228 










; reference a list of 


po inters 


229 


In i tCDev 




169 




PushLong «TextCtlList 


230 


Ida 


TUP lag ;is there a TUGS? 






; address of 1 ist 




231 


bne 


: Ok ; yup 


170 




_l\leujContro 1 2 




232 


rts 


; else no in it req'd 


171 




pla 




233 








; pu 11 the un-needed 


info from stack 


234 


:0k 




172 




pla 




235 


PushLong «0 ; space 


173 




rts 




235 


PushLong Datal ; window pointer 



237 




PushLong «3 ; ID for Speed Menu 


295 




238 




_GetCt1 Hand! eFromID 


296 


: CtlRout ines 


239 




Pull Long SMHandle ; store the hndl 


297 


da SetSpeed 


240 








; speed menu was h i t 


241 




PushLong «0 ; space 


298 


da SetlRQ 


242 




PushLong Datal ;uiindouj pointer 




; IRQ Menu was hit 


243 




PushLong «4 ; ID for IRQ Menu 


299 




244 




jQet Ct 1 Hand 1 eFrom ID 


300 




245 




PullLong flTHandle ;store the hndl 


301 




246 




302 


* Find menu item hit & set speed accord ingli 


247 




PushLong «0 ; space 


303 




248 




PushLong Datal ; window pointer 


304 




249 




PushLong «6 ; ID for Current Speed 


305 


SetSpeed 


250 




_Get Ct 1 Hand 1 eFrom I D 


306 


PushUord «0 ; space 


251 




PullLong CSHandle ; store the hndl 


307 


PushLong SMHandle 


252 








; handle for speed menu 


253 




Jsl GetTUInfo ;get version* in X 


308 


__GetCt lvalue 


254 




txa 


309 


pi a ; get value of Ctl 


255 




ora «$3030 ;make text printable 


310 


sta Oldlndex 


256 




Sep $20 ; short fl 




; store it so the menu doesn t get 


257 




sta VersNufn+2 


311 








; store the rev i s i on « in the str i ng 




; updated in the SetControls routine 


258 




xba ;swap hi t lo acc 


312 


and «$F 


259 




sta VersNum 




; we only need the low nibble 






; istore vers i on in the str i ng 


313 


dec 


260 




rep $20 ;back to long fl 


314 


asl 


261 






315 


tay ; f or i ndex i ng 


262 




PushUiord Max i mumSpd 


316 


Ida Spdlndex^y 






; push max speed for the convers i on 


317 


tax 


263 




PushLong ^MaxSpeed ; pointer to 


o lo 


js 1 oevLur iopeeo 


str i ng 






; set the current speed 


264 




PushUord «5 ; 1 ength of str i ng 


319 




265 




PushUord «0 


320 


Jmp SetControls 






;make it an unsigned number 




; update changed controls and return 


266 




_Int2Dec ; convert it 


321 




267 






322 


Spdindex 


268 




sep $20 ; short fl 


323 


dw 0^ 1 ^ 2 


269 




1 da MaxSpeed+3 ; make room for ' . ' 


324 




270 




sta MaxSpeed+4 


325 


>♦< *i< 


271 




Ida MaxSpeed+2 


326 




272 




Sta MaxSpeed+3 


327 


^ bet the nppielaik inw s^avus oT vhe card 


273 




Ida ; decimal point 


328 




274 




sta MaxSpeed+2 


329 




275 




rep $20 ; 1 ong fl 


330 


SetlRQ 


276 






331 


PushUord ^^0 ; space for result 


277 




Jmp SetControls 


332 


PushLong flTHandl e; hndl for IRQmenu 






;set remaining controls and return 


333 


__GetCt 1 Val ue 


278 






334 


pi a 


279 








;get the controls value 


280 


>♦< 




335 


sta OldlRQ 


281 




This is routine that is called every time 




; store so menu doesn't get 


282 




the user selects a menu option. 


336 




283 






; updated in SetControls routine 


284 






337 




285 


H i tCDev 


338 


and «$F 


286 




Ida Data2 ;get controls ID 




• iiio f^¥^ 111 iii^i^'^ 1 f^iii i hih) 1 a 
, lU^ sjfi 1 ^ luofi V 1 yJ UJ r 1 I uu I ^ 


287 




sec 


339 


dec 


288 




sbc n2 


340 


beq iIRQOn ;turn on IRQ 






;we can only hit controls 3 & 4 


341 




289 




cmp «2 ;bad hit? 


342 


Jsl DisablelRQLogic 


290 




bge :TooHigh 


343 


rts 


291 




asl 


344 




292 




tax 


345 


:IRQOn Jsl EnablelRQLogic 


293 




Jsr C : Ctl Rout i nes, x) 


346 


rts 






; handle the control action 


347 




294 


:TooHigh rts 


348 







>*( 






; handle to control 


350 


* This routine 


1 called every time my 


406 


SetCtl Vdl u@ 


Q^s 1 
1 


* CDev gets a 


run event. It calls rtn to 




; and set the value 




♦ make sure cntrls display correct values 






OOo 








rusnLong n i nancj i e 




nunv^uev 






; push i t aga i n 




i da 


! Nr 1 ag ; 1 Nub 1 n macn i ne r 




^urawunev v i 




bec) 


:none ;no 




; and draw i t 




Jsr 


oe vuon vro i s ; yes~"Upda ve c v i s 


410 






: none rts 


All 


: oameinW 


359 






412 


Jsl GetCurlSpeed ;get speed indx 










cpx 


ool 






414 


D 1 :Lonv 


oOc 


r 1 nd ou V i T 


TransUarp GS i s i nsta 1 1 ed . 


410 


1 dx *c 


oOo 








; IT 1 s more tinan c., jusv make \x c. 


oo*t 


1 i rivj 1 1 or Id HOI 






. uon V cpx *i 


ODD 


S vZ 


Twr 1 ag ; assume no card 




; i f it's a 1 we m i ght have to fix it 


oDO 


Idal 


TransUarpID ;get tID bytes 


4 1 r 


bne : IMoProb ;for older cards. 


oD r 


cmp 


«'TW' ;must match 'TUGS' 


4 1 o 


1 ca 1 HL'OnT 1 g 




bne 


:NoTWFnd 


419 


jrind 11X0000 CSOiCiQi OiOSOi(A 0100 

OliVJ ^^%JKJ%J%J WW WW vxw 


OQa 


Ida! 


TransUarp I D-»-2 
« 'GS • 




; 1 s vne i w i i ag seu f 




cmp 


4?0 




371 


bne 


: IMoTUFnd 


421 


1 dx ^2 


372 


sta 


TUP lag ; found so make flag 


422 




373 




; anything but zero 


423 


: IMoProb i nx ; bump i t f or i tem number 


374 


Jsl 


GethaxSpeed ;get max speed 


424 


txa 


37S 

w f >J 


sta 


MaximumSpd ; store for later 


4PS 


nr^^ 11^3000 •m^Uo i '1' mtfanu li'^m TFl 
v^r o ^^^vvv ^ iiiotsc 1 V iiiciivi 1 vein xu 


376 


Jsl 


Preq2 Index 


426 


cmp Oldlndex ; already set? 




;make index 


[returned in X) 


427 


beq :SameIndex ;yup^no chg req'd 


377 


cpx 


«1 




^vo uiuinvjex ^ 5ove i or nxv viine 




;old ROMs return a 1 here (wrong value) 


429 




37fl 
O r o 


bne 


:0k 


430 


pha 


O f vJ 


Idx 


«2 


4ol 


D 1 U.i OMI_l->^^1 

rushLong onnand 1 e 




:0k stx 


SpdIndex+4 ] 




jhndl for speed menu 




; store i n i 


ndex table 


4oc 


_SetCtl Value ;set the new value 


381 


:NoTWFnd rts 




TOO 










434 


PushLong SMHandle ; push it again 


383 






43^ 


rii'^^iiini^or 'f" i • ^i^iH t^oHv^^m \ ^ 

iJT ouiv^ricv^ V 1 , oiiu 1 cvjf oui i v 


384 


* 




*TOO 




385 


* Ck cntrls that can be updated 


437 


. oameinvjex 


385 


* If changed. 


the control is redrawn 


438 


Jsl GetCurSpeed 


387 


* with the correct value. If no change. 




; get current speed i n Khz 


388 


* this call does nothing. 


A OQ 


vax 


389 


* 




Ail 01 


cmp ^CLOXiXJ 


390 








; 1 T its 2o00 we m i ght need it t i xed 


3^1 


SetControls 




A A 1 

441 


bne : NoF i x 




Jsl 


GetTUConf ig 




; nope, no problem then 


333 


;get the configuration word 


44c 


1 da 1 UC/Ont 1 g 


Idy 


«1 


/I /I o 

44o 


4* if mmfx/Ti nokOka nfxnn aiaa 

and WW 


394 


sta 


TUConf i g ; save i t 




. 1 «r -l-K^ TU -rijan c-q+"3 

, 1 5 vne 1 w T 1 ag se v f 


39S 


and 


«;?0000_0000_0000_1000 


444 


beq :f\loFix 




; check the 


IRQ bit [0 = on) 




;nope. false alarm 




beq 


:0n 


445 


Idx «7000 


397 


Idy 


«2 




; 1 V IS on o 1 u Conci so ni^K€ vne 


398 


:0n tya 


;put it in fl reg. 




; speeu — r i inz . 


399 


era 


«$4000 


447 


. IMV/l 1 A 




; make i t a 


menu item ID 


448 


txa 


400 


cmp 


OldlRQ 


449 


cmp OldSpeed ; already set? 


401 


; IS It already set 


450 


beq iSameSpeed ;yup^ Just leave 


beq 


:SameIRQ 


451 


sta OldSpeed 




jit's already set. No need to change 




;save it for nxt time through 


402 


sta 


OldlRQ 


452 




jsave for next pass 


453 


pha 


403 








;push it for the conversion 


404 


pha 




454 


PushLong «CurSpeed ;ptr to string 


405 


PushLong flTHandle 


455 


PushUord «5 ; 1 ength of str i ng 



456 

457 
458 
453 
460 
461 
462 
463 
464 
465 
466 
467 
468 



PushWord <t0 
;uie want an unsigned number 



ZBasic Tricks 



Int2Dec 



Sep 
Ida 
sta 
Ida 
sta 
Ida 
sta 
rep 



$20 

CurSpeed+3 
CurSpeed+4 
CurSpeed+2 
CurSpeed+3 
«' . ' 

CurSpeed+2 
$20 



; convert it 
; short fl 

;inake room dec pt 



; decimal point 



; 1 ong fl 



;hndl 

469 
470 

471 :SameSpeed 

472 rts 

473 

474 * 

475 * 
* Data area 



PushLong CSHandle 
for text Ctrl 
DraujOneCtl ;drauj 



it 



476 
477 
478 

479 Message 

480 Datal 

481 Data2 

482 SMHandle ds 

483 flTHandle ds 

484 CSHandle ds 



ds 
ds 
ds 



2 
4 
4 
4 
4 
4 



;msg passed to me 
;data passed 
jdata passed 
; speed menu handle 
; IRQ menu handl e 



; current speed text control handle 



485 TUFlag ds 2 

486 OldSpeed ds 2 

487 Oldlndex ds 2 

488 OldlRQ ds 2 

489 TUConf ig ds 2 

490 haximumSpd ds 2 



is there a TUGS? 



; TW conf i gurat i on word 
; maximum speed of card 



Listing 3 - RPU Make File 

echo creating TransUarp CDev 

compile tuj . rez keep=TransUarp rez= C-t $c7] 

dupl icate TransWarp */system/cdevs/TransWarp 



ing Data 
Into Aiixmem (& 
Elsewhere) 



by Ross W. Lambert 

I recently completed a very small contract program- 
ming j ob with some interesting implications for ZBasic 
programmers. Before I dig into it, though, I'd like to 
thank University of Wisconsin Professor Ron Myren 
for his willingness to let me share with y'all some of the 
things that I developed while under contract with him. 
Although I know that recent copyright law related 
court decisions have not made it necessary, I have nev- 
ertheless placed these routines under copyright in 
Ron's name. He has granted you folks (i.e. 8/16 
subcribers) permission to use them, a gesture I find 
quite refreshing. Thanks, Ron. 

Prof. Myren wrote a database in ZBasic that did not 
use the graphics modes - it was 80 column text only. 
Since ZBasic reserves the graphics pages, the good 
professor Just knew there had to be away to access 
that extra 16K of memory . 

The professor was quite correct. The only trouble is 
that ZBasic does not allow us to put arrays or other 
data into the graphics pages directly. That is good, in 
some cases, becase there is no hassle when you want 
to jump to a graphics mode. You can do so at any time 
and with no hesitation. 

If you neuer want graphics, however, this situation is 
a waste of memory. And 16K is a lot of real estate on 
128K Apples. 

All of these things meant, therefore, that Td have to 
manage the two 8K banks of memory on my own. As 
things turned out, this was not very difficult at all. In 
fact, the routines I developed provide the flexibility to 
manage the memory as either integer, floating point, 
or string arrays. 

A little background: Professor Myren did not need 
blazing speed for retrieving a single element out of the 
extra memory space. Instead, he needed some zip for 



©/a© assiJKgih, mm iMg(B m 



moving an entire block of memory into the the extra 
array. The length of our array management routines 
was a consideration, too, hence the shorter the code the 
better. For those reasons, (and for flexibility's sake) I 
decided to use the built in ROM routine called 
AUXMOVE, called via some in-line MACHLG state- 
ments. 



CaU the AUXMOVErs 

AUXMOVE just needs to know the address of the source 
data, the address of the destination, the number of 
bytes to move, and the direction of the transfer (i.e. 
auxilliaiy memory to main or main to aux). Because 
AUXMOVE will shufile around the number of bytes you 
specify, it makes managing different types of arrays 
easier. 

But let's begin at the beginning. 

I decided to create a couple of **building block** functions 
before I got too far along. Since the project called for 
integer arrays, I called the two functions 
AuxPEEK_WORD and AuxPOKE^WORD. These little 
gems allow us to PEEK and POKE word sized values (two 
bytes) from and to aux mem at will. This is slightly 
dangerous, however, because so much of ZBasic proper 
lives over there. For our purposes, though, (PEEKing 
and POKEing around on the graphics pages) we are in 
pretty safe waters. 

Admittedly, AuxPEEK_WORD and AuxPOKE_WORD 
do not do their jobs as fast as they could. However, 
because they use the protean AUXMOVE routine they 
can be changed to AuxPEEK_ELEMENT and 
AuxPOKE^ELEMENT quite easily. In such an instance, 
the length of your elements (and, hence, the amount of 
data moved about) would change to match the precision 
(i.e. number of bytes) of the floating point variable you 
were using or the length of the strings in your pseudo- 
array, etc. 

The next function I created was FN BLOCKMOVE. I was 
veiy pleased at the speed with which AUXMOVE 
shuffles large blocks of memory around. This function 
would be useful if you wanted to move an entire array 
down into aux mem for storage, for example. By the 
way, if you want to find the address of any array, use 
VARPTR(Array(0)). And remember that ZBasic puts all 
of its variables in main memory. We are the ones getting 
tricky by shuffling them into aux mem. 



After working out the first few functions, finishing 
things up was easy. FN XArray examines the parame- 
ters you pass and determines whether you want to read 
or write to main or aux mem. It will deposit any integer 
value you wish into any element of either the main bank 
array or the aux bank array. 

Easy stuff. 

Using FN XArray is even easier. Just think of the two 
banks of memory as you would any other array. If you 
want to have a look at the main mem array element 
number five, you can do so by calling the function like 

so: 

IntValue = FN Xflrray CO. 5. 0,0) 
In general, the syntax looks like this: 
Int = FN Xflrray [Bank, El ement, RdUr i te, Val ] 



...where Bank is zero for main or a one for aux mem. 
Element is the element number in the array, RdWrite is 
a zero for read or a one for write, and Val is the integer 
to deposit into the array on a write operation. Val is 
ignored during a read, but the function itself retums 
the integer read. 

One of the nice things about using a set of functions like 
these is that you don't need to calculate offsets into the 
range of memory you're using. The function does it for 
you. If you change the element size, however, the second 
line of the FN XArray function needs to be changed to: 

Offset - Element * ElementSize 



Note that the function will do its work mucho faster if 
you can use the bit-shift operators, changing the line 
above to something like: 

Offset = Element << 4 



This is not possible if you have odd sized array elements, 
but if speed is a very high priority, you may want 
consider wasting a byte per element. Bit level multipli- 
cation (i.e. in powers of 2) operates as much as 10 -20 
times faster than standard integer multiplication. Of 
course, if speed is that important, you will want to write 
some custom assembly code that does not use 
AUXMOVE. 



Variations on the theme 

There's a Jillion ways you can mold FN XArray to better 
suit your purposes. One thing I expect to do fairly soon 
is amend the function so that it manages both graphics 
pages as a single 1 6K array. This could be accomplished 
by having the function deposit even numbered elements 
in main mem. odd numbered elements in aux mem. Or. 
faster yet, the first 8K of elements goes in main mem. 
the second into aux mem. 

Since IVe had numerous questions of late regarding 
connecting assembly code and ZBasic, and since these 
functions may inspire you to try your hand at it, I 
thought rd digress a tad and discuss some of the 
considerations in general terms. Vll get into more detail 
next month. 

If you are interested in crafting custom assembly lan- 
guage code, keep in mind that your ^asic program 
code is executing in auxilliary memory. This means that 
MACHLG statements - or, more accurately, the assem- 
bly code they represent - will be executing in aux mem, 
too. Furthermore, remember that your routine needs to 
be completely relocatable because there is no way to 
predict its final address. 

One altemative to MACHLGs is the dimensioned buff- 
ering technique. Since ZBasic variables and arrays live 
in main memory, you can dimension an array equal to 
the size of your assembly routine, get its address with 
VARPTR. and then BLOAD the routine into that loca- 
tion. Don*t forget to terminate your assembly stuff with 
an RTS and to avoid making any internal references. To 
use the code, just CALL Address. 

If you don*t want to BLOAD a routine, you can always 
convert the machine language hex codes to DATA 
statements and then POKE them into an array. Again, 
there are a few caveats: you can only POKE into main 
memory and the location of your array space is not 
easily nailed down. Your routine needs to be relocat- 
able. 

I am in the middle of experimenting with fixed position 
code deposited at the start of variable space ($ACOO less 
IK for each file buffer). It seems to be working but IVe 
not thoroughly tested it yet. Something tells me Fm 
playing with fire.. . my ZBasic tells me that the variable 
space starts at $A336, though the manual insists that 
it should be starting at $A400 ($AC(X)-$0800). 



If you have a very short assembly routine, you can stick 
it at 768 in main memory. ZBasic does not use locations 
768 - 975. hence it is also available for fixed position 
code. 



The Future? 

I love ZBasic. I develop ZBasic tools. This column 
evolved from my old Znews newsletter. But there comes 
a point when times and situations change. No, Fm not 
going to quit writing about ZBasic. But I wouldn*t be 
doing my job if I blindly refused to consider other 
BASICS. 

The reason is simple: Zedcor is a Macintosh company 
and is no longer actively developing Apple II software. 
ZBasic is good, but it will not get better, at least not right 
away. I can live with that - though I don*t agree with it. 

Micol Systems of Canada, however, has continued 
improving their BASICS, both OS and 8 bit. Frankly, I 
was not impressed with either version initially. But the 
Micol folks stuck with it (perseverance counts, my 
friends), and their BASICS (both 8 and 16 bit) have 
progressed a long way. There is now a lot to recommend 
them. 

Two of the most significant advantages their 8 bit 
version has over ZBasic is a wonderful editor and local 
variables. Local variables make large scale and multi- 
programmer development significantly easier. To be 
honest and above board, I must tell you that I am now 
selling MicoFs BASICs, so I am not particularly unbi- 
ased. In my own defense, I only sell products I believe 
in - 1 have to operate that way because of our uncondi- 
tional money back guarantee on all of our products. 

But this isn't an ad, so Til click on the close box and 
close this window. After I do, I hope that you Z-fans find 
these functions - and the extra 16K of variable space 
they allow you to have - quite useful. 



Bonus Code 

In addition to my featured listing, the Extra Array 
Functions. I have tacked on a fun little routine called 
PROGRESS. FN. This is a little gizmo that will draw a 
thermometer-like scale in a box and update it as any 
long process happens. 



To use PROGRESS.FN, just insert it inside a loop or 
deposit it at selected points during long calculations, 
disk reads/writes, etc. I use it most when looping 
through and writing array elements to disk. It*s fairly 
fast and doesn't slow down the process at all (well, at 
least not noticeably). 

The sjnitax looks like this: 

FN PROGRESS CX, V, Rmount, Total) 

X and Y are the text screen coordinates of the upper left 
hand comer of the thermometer's box. Amount is the 
current status of the procedure being timed. That is, 
let's say you were writing 1000 strings to disk; Amount 
would be the current string you were working on. Total 
is the total number of strings, calculations, etc., that 
you needed to complete. In our 1000 string example 
above Total would be equal to 1000. 



PROGRESS.FN displays a percentage, but you don't 
need to figure it out - the function calculates it for you 
automatically. 



Percent Complete 50% 










0% 25% 50% 75% 


100% 



The PROGRESS.FN Thermometer Box 



I hope you have some fun with it. PROGRESS.FN adds 
a very professional touch to your code without taking up 
very much space. 

As will be my custom, I would like to close this column 
with the three "nevers" (with apologies to Chris Stasny): 

One: Never get into an argument with a programmer 
about assemblers or pizza. You cant win, and you won't 
even get a byte. 

Two: Never confuse a ringing phone with a CALL or a 
drug addict with a USR. 

Three: Never , never, underestimate the power of BA- 
SIC. 

== Ross == 



Extra Array FN listing 

REM Extraflrray FN " 
REM 

REM by Ross W. Lambert 

REM a Uork For Hire for 

REM Ron Myren, Univ of Ui scons In 

REM Copyright CCD 1989 

REM ============================== 



REM Equates for fluxMove [Rpple nomencla- 
ture, lie Ref Man. p92] 

fllL =&3C :REM source, low byte 
fllH =&3D :REM source, high byte 
fi2L =&3E :REM end of source, low byte 
fl2H =&3F :REM end of source, hi byte 
fi4L =&42 :REM destination low bute 
fl4H =&43 :REM destination high byte 

LONG FN fluxPEEK^UORD CRddress) 
REM source start 

POKE UORD filL,fiddress 
REM source end Conly 2 bytes] 

POKE UORD R2L,nddress+l 
REM destination is IntVar 

POKE WORD fl4L,VflRPTR [IntVar] 
REM clc Cmeans aux to main] 

MflCHLG &18 
REM jsr fluxMove 

MflCHLG &20,8cll.&C3 
END FN = IntVar 

LONG FN fluxPOKE WORD [Rddress, Val ue] 
REM location of integer to POKE 

Valueflddr = VflRPTR (Val uel 
REM source start [lowbytej 

POKE WORD fllL, Valueflddr 
REM source end Chighbyte] 

POKE WORD fl2L,Valueflddr+l 
REM destination 

POKE WORD fl4L,flddress 
REM sec Cn^oves mem from main to aux] 

MflCHLG 8c38 
REM jsr fluxMove 

MflCHLG 8c20,&ll,ScC3 
END FN 



REM FN BlockMove - move chunks of memory 
between main & aux mem 

REM * If Direction = 0, then the move will 

Qo MflIN to flUX 
REM * If Direction <> 0, then the move 

will go flUX to MflIN 

LONG FN BlockMove CD i r, Start, End, Dest] 
POKE WORD fllL, Start 
POKE WORD fl2L,End 
POKE WORD fl4L,Dest 

REM aux to main 
LONG IF Direction = 1 

REM clc Cn^ove from aux to main] 
MflCHLG 8cl8 



XELSE:REM main to aux 

REM set carry. . . 

nnCHLG 8c38 
END IF 

REM jsr auxmove 
MflCHLG 8c20.8cll,8cC3 
END FN 

LONG FN KRrray (Bank , E 1 ement , D i r , I nt 3 
REM binary double (2 bytes each] 
Offset= Element << 1 
REM calculate actual spot in memory 
Elementflddr = 8192 + Offset 

REM can^t 1 ook or wr i te outs i de 8K 
IF Elementfiddr > 16383 THEN ^ut^ 

REM write? 

LONG IF Direction = 1 
REM main mem? 
LONG IF Bank = 

REM if so. simple POKE WORD 
POKE WORD Elementfiddr. Int 
XELSE :REM nope, aux mem 
REM still simple! 
FN fiuxPOKE^WORD [El ementflddr . Int) 
END IF 

XELSE: REM no. uie REflDing from array 
LONG IF Bank = 

IntVar = PEEK UORD CEl ementflddr ] 
XELSE 

IntVar = FN fluxPEEK WORD [Elementfiddr} 
END IF 
END IF 
"Out" 

END FN = IntVar 



REM Demo 

Main = : fiux =1 
Read =0 : Write = 1 

CLS 

PRINT "To main: "."To fiux:" 

FOR Element = TO 9 
FN Xfirray fMa in. El ement. Write. El ement*2) 
FN Xfirray Cfiux. El ement. Wr i te. El ement*3) 
PRINT Element*2.Element*3 

NEXT 

PRINT "From Main: "."From fiux:" 

FOR Element = TO 9 
VarMain = FN Xfirray f Ma i n. El ement. Read. 0) 
Varfiux = FN Xfirray ffiux. El ement. Read. 0} 
PRINT VarMain. Varfiux 

NEXT 



PRINT "Press RETURN. . ." 
INPUT R$ : CLS 

PRINT "Speed test 1: Writing to main array 

1000 times. . . " 
FOR Element = TO 999 

FN Xfirray CMa i n. El ement. Wr i te. aFF) 
NEXT 

PRINT CHR$C7D;"Done!" 
PRINT 



PRINT "Speed test 2: Writing to aux array 

1000 times. . . " 
FOR Element = TO 999 

FN Xfirray CMa in. El ement. Write. &FF] 
NEXT 

PRINT CHR$(7];"Done!" 
PRINT 

PRINT "Speed test 3: Reading from main 

array 1000 times..." 
FOR Element = TO 999 

FN Xfirray [Ma i n. El ement. Read. 8cFF] 
NEXT 

PRINT CHR$C7]; "Done! " 
PRINT 

PRINT "Speed test 4: Reading from aux 
array 1000 times..." 
FOR Element = TO 999 

FN Xfirray Cfiux. El ement. Read. 0) 
NEXT 

PRINT CHR$C7);"Done!" 
PRINT 

REM This is amazingly f ast I ! ! 

PRINT "Speed test 5: Moving a 2000 byte 

block from fiux mem to Main..." 
FN BlockMove Cl . 8192. 8192+2000. 8192] 
PRINT CHR$C7];"Done!" 
PRINT 

PRINT "This completes the test" 
END 



PROGRESS.FN Listing 



REM 

REM Progress FN 
REM 

REM by Ross W. Lambert 

REM Copyright CC] 1989 

REM Most Rights Reserved 

REM ========================= 

DIM 3 MouseText$.Norm$. Inverses. 4 PERCENT$ 

inverses = CHR$[15] 

MouseTextS = CHR$C27D + CHR$C15] 

Norm$ = CHR$C14] + CHR$C243 

LONG FN PERCENT$CfiMOUNT.TOTfiL) 

PC! = fiMOUNTSTOTfiL 

PC! = PC! * 100 

PERCENT! = STR$CPC!3 

PERCENT! = LEFT$ (PERCENT!. 4) + "%" 
END FN = PERCENT! 

LONG FN Progress CfiMOUNT. TOTfiL. XPOS. VPOS] 
BoxLen = 53 
LONG IF FIRSTPfiSS = 

LOCfiTE XPOS+l.YPOS 

PR I NT STR I NG! CBoxLen- 1 . " _" 3 

LOCfiTE XPOS+l.YPOS+4 

PR I NT MouseTex t ! ; STR I NG! CBoxLen- 1 . " L " ) 
LOCfiTE XPOS. VPOS 



mm 



FOR ZV = VPOS+1 TO VPOS + 3 
LOCATE XPOS.ZV : PRINT "Z" 
LOCRTE XPOS+BoxLen^ZV: PRINT " " 

NEXT 



PRINT Norm$; 
LOCATE XPOS + 

compi ete : 
LOCATE XPOS + 
PRINT •• 0X 

75Z 

FIRSTPASS = 1 
XELSE 

LOCATE XPOS + 



2. VPOS + 1 : PR I NT "Percent 
•■;FN PERCENT$CAMOUNT, TOTAL) 
2, VPOS + 3 



3, VPOS +2 
BARLEN =CAMOUNTSTOTRL] +50.0 
BAR$ = STRINGS CBRRLEN,CHR$C32D] 
PRINTe CXPOS+2, VPOS+2] Inverses ; BAR$; Norm$ 



LOCATE XPOS + 20. VPOS + 1: PRINT FN 
PERCENTS (AMOUNT, TOTAL) 
IF PERCENTS = " 100X" THEN FIRSTPASS 
: REM reset flag 
END IF 
END FN 



REM Demo 
liODE 2 

FOR X = 1 TO 50 

FN Progress [X,50,5.5D 
NEXT 



LOCATE 1,20 
END 





lIGS Animation 









The Illusion of Motion 

by Steven Lepisto 



Editor: Animation is one of the most enjoyable and 
gratifying topics in programming. Remember the thrill 
you felt when you plotted your first high res shape on the 
'ol //+? The Ilgs has been a different story for most of us. 
however. Even simple shapes (let alone movement!) 
seem beyond reach. 

For that reason I consider us doubly blessed to have two 
of the best GS animators inAppledom willing to teach us 
the art of animation. These gentlemen, Steven Lepisto 
and Chris McKinsey, will not only be sharing the "state 
of the art" with us, but since they have room to stretch out 
over several months - even years - we've also given them 
the freedom to take it step by step. Best of all I bet they'd 
even be willing to handle some of your animation ques- 
tions within their respective articles. == Ross == 



Animation. It is defined as the illusion of motion. It is the 
process of taking a series of unmoving images and 
making them appear to move. These articles will focus 
on how to do animation on the Apple Ilgs computer from 
assembly language. It will start at the beginning with 
the basics, moving on to more and more complex 
concepts as we progress. I assume you have a working 
knowledge of 65816 machine language and a basic 



understanding of the IIgs*s hardware. The basic con- 
cepts of animation are independent of the computer 
language used to implement them. However, since I 
happen to like working in assembly language, that is the 
language this article is geared towards. I use the Merlin- 
16+ assembler. IVe attempted to code the program to 
minimize problems if you wish to convert the code to 
Orca/M or APW assemblers. 

The program presented here is the start of several. We 
will build on this one program and it will give us a 
platform on which to experiment with different tech- 
niques of animation. In each new article, I will suggest 
some areas in which you can experiment on your own. 
I encourage your playing with the code as experience is 
the best teacher. 

Goals of lesson 1 : 

1) Get a program up and running. 

2) Get two images bouncing around the screen. 

a) show how motion is achieved using velocities and 
positions. 

b) show how to draw to the shires screen directly. 



TIRED OF SWAPPING DISKS? 



THEN YOU NEED A KAT HARD DRIVE! 
BUILT YOUR WAY! 

KAT hard drives come in industrial-quality cases that have, (115-230 
volt) 60 watt power supplies, cooling fan, two 50-pin connectors and 
room for another half-height drive or tape back-up unit. Also included 
is a 6 ft. SCSI cable to go from the drive to your SCSI card. Now for 
the good stuff! You will also receive 20 meg of freeware, shareware, 
fonts, System 5.02 and public domain software. your drive will have the 
interleave and partitions set for You before the drive is exercised for 
24 hours. You get all of this and a one-year parts and labor warranty! 



SB 48 Seagate 48 meg 40m8 $549.99 

SB 85 Seagate 85 meg? = $698.99 

SB 105 Quantum 105 n.^^ x^i.y. ^ ........ $899.99 

SB CASE 2 HH Drives 7w 5h 16d $139.99 

ZF CASE 1 HH Drive lOw 3h 12d $169.99 

48 meg HD Seagate 40ms 3.5" SCSI $349.99 

85 meg HD Seagate 28ms 5.25" SCSI $469.99 

105 meg HD Quantum 12ms 3.5" SCSI $699.99 

T-60 TAPE Teac60megSCSI $449.99 

W/ Hard Drive $424.99 

3.5" to 5.25" FRAME $12.50 

CABLE 25 pin to 50 pin 6 ft $19.99 

50 pin to 50 pin 6 ft , $19.99 



NEW PRODUCTS! 



VITESSE Inc. Salvation 

Salvation is a slick new GS/OS-based volume backup/restore program 
for the IIGS. You can backup multiple, single or portions of large 
block devices including hard drives, RAM drives and ROM drives to 
3.5" or 5.25" disks. Do you need to stop in the middle of the backup to 
get to an important file? No problem with Salvation. It remembers 
where you left off and starts back up at that point. Uses the familiar 
Apple Desktop Interface. $39.99 

QUICKIE 

Quickie is the hand-held scanner we've all been waiting for! You get 
up to 400 DPI and 16 shades of gray. Watch the image apear on the 
screen as you scan then import it into your favorite paint, draw or 



graphics program. $249.99 

COMPUTER PERIPHERALS ViVa24 

The ViVa24 is a 2400 baud modem that is 100% Hayes compatible. 
Unique "tower" design allows for better viewing of the status icons 
used in place of cryptic LED's on some modems. Comes with a FIVE - 
YEAR WARRANTY! $139.99 

HARRIS LABORATOIES, Inc. GS Sauce 

The GS Sauce is a compact memory board that differs from most of 
the rest. It uses low-power, cool-running CMOS SIMMs like the Mac. 
You can use 256K or 1 meg SIMMs for a total of 4 megs. Made in the 
USA. Limited lifetime warranty. $79.99 

1 meg SIMMs 80 n§ $89.99 

1 meg X 1 80 ns 8 / $79.99 

JE Conserver $79.99 

JE Transwarp GS $289.99 

AI Juice Plus W/1 meg $144.99 

CH PRODUCTS FLIGHT STICK $49.99 

KENSINGTON SYSTEM SAVER GS $69.99 

KENSINGTON TURBO MOUSE ADB 119.99 

KEYTRONIC KEYBOARK 105 KEYS ADB $139.99 

BYTE WORKS ORCA/C $89.99 

BYTE WORKS ORCA/M $44.99 

BYTE WORKS ORCA/PASCAL $89.99 

BYTE WORKS DISASSEMBLER... $34.99 

CHECKMATE PROTERM 2.1 $89.99 

ROGER WAGNER HYPERSTUDIO $94.99 

ROGER WAGNER MACROMATE $37.99 

STONE EDGE DB MASTER PRO $219.99 

GENERIC 3.5- DS/DD BULK 50 / $.69 



Phone: (913) 642-4611 
Or Mail Orders To: KAT 

8423 W 89th Street 
Overland Park, KS 66212-3039 



The first thing you need to do is type the program in. If 
you get the disk that goes with this issue, you are spared 
the tj^ing. For the rest of you, type the program in. 
Before saving it, comment out the "use animl.macs" 
line so we can build a macro file. Save the program 
under the name ANIMATION 1. Now, from the editor's 
command box, type "mac ANIMATION 1" and proceed to 
build the macros. The program uses the super macros 
supplied with Merlin- 16+. When all the macros have 
been gathered, save the file under the name 
ANIM I.MACS. Then reload ANIMATION 1 and restore 
the "use animl.macs" line. 

Assemble the program with open apple-6. If there are no 
errors, you can run it from the disk command menu 
with "=ANIMATIONl". After a moment or two, you 
should see a blue diamond and green square zipping 
around a black screen. When you get tired of that, press 
a key or the mouse button to exit. We will use this 
procedure throughout the series to run the programs. 



What's It Doing? 

Motion of the images is achieved by the use of a change 
in position applied as a vector (a vector is a line with a 
direction). This change in position vector is called 
velocity. To move the image, you add the veolicty to the 
current position of the image to get a new position. You 
then erase the image from the old position and redraw 
it at the new position. In the program, the position of the 
image is represented by an X,Y coordinate (Y indicates 
which row and X indicates which pixel on that row the 
image is on). The velocity is broken up into two compo- 
nents: the horizontal or X velocity and the vertical or Y 
velocity. By adding the components of the velocity to the 
proper part of the coordinates, the image can move in 
any direction. 

The coordinates used in the program have the origin 
(where X and Y are both 0) at the upper left comer of the 
screen. Incrementing X moves to the right and incre- 
menting Y moves down. So for example, to move the 
image left one pixel, you add to the X coordinate an X 
velocity of -1 and to the Y coordinate you add a Y velocity 
of (it isn*t moving in that direction). To move the image 
at a 45 degree angle (down and to the right one pixel), 
you add an X velocity of 1 to the X coordinate and a Y 
velocity of 1 to the Y coordinate. 

When the image hits a boundary, it is bounced off in a 
predictable way. This bouncing is achieved by inversing 



M^(gih, mm 



the appropriate velocity (converting it from negative to 
positive and vice versa) . If the image hits the left or right 
boundaries, inverse the X velocity. If the image hits the 
top or bottom boundaries, inverse the Y velocity. This 
causes the image to reflect from the boundary hit as you 
would expect it to. To see the code for this, look at the 
routine MOVEJMAGES. I first add the X velocity to the 
X coordinate then check that new position against the 
left and right boundaries. If the image hits a boundary, 
I inverse the X velocity and set the new position to that 
boundary. This way. the image looks like it hits the 
boundary. 

One thing to note here is by adding the velocity to the 
position to get a new position, the image doesn't move 
through all intervening positions: it jumps to the new 
position. This is why I set the image to the boundary 
that was hit; otherwise if the velocity was large enough 
it might look like the image bounced off an invisible 
barrier in front of the boundary instead of the boundary 
itself. 

If you make the jumps small enough the eye sees 
smooth motion. To give the illusion of greater speed, you 
can increase the size of the jumps. However, if the jump 
is too large, the eye will not be able to track the image 
well and it will look like it is skipping or stuttering. In 
the program, the range of the horizontal and vertical 
velocities is 0, 1, and 2. This represents the number of 
pixel positions to jump each time MOVEJMAGES is 
called. The reason for the limit will be explained a little 
later. If you do increase the velocities beyond 2, the 
images will leave a trail behind them. 

So, by adding an X velocity to the X coordinate, you 
cause the image to move left or right and by adding a Y 
velocity to the Y coordinate, you cause the image to 
move up or down. Adding both velocities at the same 
time causes the image to move in other directions. By 
increasing the velocity, you increase the apparent 
speed of the image. That's pretty much all there is to 
moving an image on the screen. 



How's It Doing It? 

Animation on a computer is generally not a simple 
thing. The basic steps of motion are: 

1) Draw image at the specified coordinates 

2) Update the coordinates with the velocity 

3) Erase the image from the original coordinates 



4) Draw the image at the new coordinates 

This process needs to be done in such a way that the eye 
sees only the change in position of the image (which 
gives the illusion of motion). If the erasing step becomes 
visible, the eye will see that and the illusion will be 
interrupted. This phenomenon is called flicker. The goal 
of animation on the computer is to eliminate flicker for 
flicker is a Bad Thing (unless you want it for an effect — 
for now. we don*t). 

There are many techniques for eliminating flicker and 
we will discuss several of them in coming installments. 
The technique Fm using in the program is the simplest: 
combine the erasing and drawing steps so the image is 
never completely invisible to the eye. This technique 
only works on a background that is mono-colored (in 
this case, black). Notice how the images are defined in 
the source code. See the border of O's around the 
images? That border is the same color as the back- 
ground so if you draw the image then redraw it shifted 
to one side, the border will erase that part of the old 
image not overlapped by the new. This is how to 
combine the erase and the draw. 

There are advantages and disadvantages to this 
method. 

The advantages are: 

1) Speed. Things go a lot faster if you don*t have to worry 
about preserving the background. 

2) The amount of memory needed to store the graphics 
can be lessened significantly over other techniques. For 
example, one technique for preserving the background 
requires the use of an image mask which eliminates the 
erasing border by making it essentially transparent 
(and yes, this does mean another way is needed to erase 
the background). However, having a mask for every 
image will double the amount of memory required to 
hold the images. 

The disadvantages are: 

1) Images can't overlap. If they do, the border not only 
erases the old image but the image being overlapped. 
You can see this occasionally as the blue diamond 
passes over the green square. 

2) The background must be the same color as the 
erasing border (or vice versa). This tends to limit the 



background graphics quite a bit. 

3) You can't use too large of a velocity otherwise the 
image will be displaced too far for the erasing border to 
have an effect. And if you want large velocities, you can 
add a larger erasing border but then you start spending 
more and more time drawing the image to the screen as 
it gets larger and larger and more and more of that time 
is spent in erasing. You need to draw the line at some 
point. In this program the width and height of the 
erasing border is 2 pixels. This is why you shouldn't 
increase the velocities in the program past 2: you will 
displace the image more than two pixels and the erasing 
border won't work. 



In Conclusion 

So, that's all this program is really doing: adding 
velocity components to coordinates and drawing 
images at those coordinates. This is the essence of 
animation, the Illusion of Motion. 



Things To Experiment With 

There are a number of things to play with in this 
program. By all means, feel free to experiment beyond 
the suggestions. 

1) In the routine ANIMATE, there is a call to 
PAUSE_A-MOMENT. Increase or decrease the value 
being loaded into the A register to slow down or speed 
up the overall motion. Set the A register to to get the 
fastest motion. Slowing down the action can get you a 
better look at the images' motions. 

2) If you wish, you can try adding more of the basic 
images to the display. First, modify the constant MAXI- 
MAGES to the number of images you want. Then, at the 
end of INrrjMAGES, modify the default arrays to add 
more images. Make sure you don't add more images 
than are allowed by MAXIMAGES. Also, make sure 
every default value is filled in for all images. 

3) Try changing the motion boundaries to smaller 
values. Be sure the default starting positions of the 
images are within the motion boundaries (the images 
won't erase properly the first time through if they start 
outside the boundaries). 

4) If you are feeling really ambitious, try adding a whole 



new image by "drawing" it in source code. Don't forget 
to modify the default arrays to reflect the size of the new 
image. And make sure the image is an even number of 
bytes wide. 

5) Finally, notice how I determine the location and size 
of the super hires screen. This technique allows me to 
easily adjust to changing conditions. It even allows me 
to run the program in 640 mode if the images were 
modified properly. 

Listing 1 - lUusions of Motion 

1 1st off 

2 rel 

3 typ sl6 

4 dsk animat ionl . 1 
5 

6 xc 

7 xc ; 65816 mode 

8 mx %(de jfull 16-bit regs 

9 cas in 

10 use an i ml. macs 
11 

12 »^==: = = = = = = = = = = = = = = = = = ======================:= 

13 * Illusions of Motion 

14 * by Stephen P. Lepisto 

15 * date: 1/22/90 

16 * Assembler: Merl in-16+ v4.08+ 

17 *=========================================== 

18 

19 * Direct page definitions 
20 

21 dum $00 

22 deref^ptr ds 4 

23 screenjDtr ds 4 

24 roujadrs_tabl e ds 4 

25 image_ptr ds 4 

26 dend 
27 

28 * « of images that can be handled 
29 

30 MflXIMflGES = 2 
31 

32 ♦========================================== 

33 

34 Start phk 

35 plb 

36 Jsr dostartup 

37 bcs shutdouin ; err i n startup 

38 Jsr Animate 

39 shutdouin Jsr doshutdown 

40 _Qu it qu i tparms 

41 brk $de ; shouldn't break 

42 

43 *" 

44 * Main loop where it all happens. 
45 

46 Animate Jsr i n i t_i mages; i n i t image arrays 

47 Jsr i n i t_boundar i es ;for motion 

48 :event_loop Jsr dr auj_i mages ;draui all images 

49 Jsr move_ images ;move all images 

50 Ida ^1 ;do a short pause 



mm 



51 






Jsr 


pause^a^moment 


117 


sta 


xvelocity^x 


52 






Jsr 


read_key 


118 


rts 




53 






bcc 


:event_loop ;no key pressed 


1 19 






54 






rts 




120 


* Invert V velocity for illusion of bounce. 


55 










121 






56 










122 


i nvert u ve 1 


Ida yvelocity^x 


57 


* Apply 


velocities to images to make move. 


123 


eor 


«$ffff 


58 


* Bounce 


off 


motion boundaries as needed. 


124 


i nc 




59 










125 


sta 


yveloci ty^x 


60 


move_i 


mages stz image_index 


126 


rts 




61 


: move_ 


.loop Ida image^index 


127 






62 






asl 




128 


>*( 




63 






tax 




129 


* Draw all images at current pes on screen. 


64 






Ida 


xpos i t i on^ x 


130 






65 






cl c 




131 


drauj_i mages : 


stz image_index 


66 






adc 


xvel oc i ty^ x 


132 


: draw^l oop 1 da i mage_ i ndex 


67 






bm i 


: 1 ; uiay past 1 ef t 


133 


asl 




68 






cmp 


1 ef t__boundary 


134 


tax 




69 






bcs 


: 2 ; not on 1 ef t edge 


135 


asl 




70 


: 1 




Jsr 


invert_xvel ;else bounce it 


136 


tay 




71 






Ida 


left boundary 


137 


Ida 


i mage_byteui i dth, x 


72 






bra 


:2 


138 


sta 


pi ot_byteuj i dth 


73 


:2 




Dha 




139 


Ida 


i mage__he i ght, x 


74 






cl C 




140 


sta 


pi ot_he i ght 


75 






adc 


i mage__uj i dth^ x 


141 


Ida 


xpos i 1 1 on, X 


76 






cmp 


r 1 ght^boundary 


142 


sta 


pi ot_xpos 


77 






pi a 




143 


Ida 


ypos i t i on, X 


78 






bcc 


:3 ;not on right edge 


144 


sta 


plot_ypos 


79 






Jsr 


invert^xvel ;else bounce it 


145 


Ida 


i mage_adrs, y 


80 






Ida 


r 1 ght_boundary 


146 


sta 


i roage_ptr 


81 






sec 




147 


Ida 


image__adrs+2^y 


82 






sbc 


image uiidth^x 


148 


sta 


i mage_ptr+2 


83 


:3 




sta 


xpos i t i on^ x 


149 


Jsr 


plot_ image 


84 










150 


inc 


image_ index 


85 






Ida 


ypos i t ion.x 


151 


Ida 


image_i ndex 


86 






cl c 




152 


cmp 


number_of_i mages 


87 






ado 


yveloci ty.x 


153 


bpc 


: draui_l oop 


88 






bm i 


:4 ;ujay above top 


154 


rts 




89 






cmp 


top_boundary 


155 






90 






bcs 


:5 jbeloui top edge 


156 






91 


:4 




Jsr 


invert__yvel ;else bounce it 


157 


* Set up motion boundaries to shires screen 


92 






Ida 


top boundary 


158 






93 






bra 


:6 


159 


in i t_boundar 


i es 


94 


:5 




pha 




160 


stz 


1 ef t_boundary 


95 






clc 




161 


Ida 


sh i res^uj i dth 


96 






adc 


lmage_he ight.x 


162 


sta 


r i ght__boundary 


97 






cmp 


bottom_boundary 


163 


stz 


top_boundary 


98 






pla 




164 


Ida 


sh i res_he i ght 


99 






bcc 


:6 j above bottom edge 


165 


sta 


bottom_boundary 


100 






Jsr 


Invertjyvel ;else bounce it 


166 


rts 




101 






Ida 


bottom_boundary 


167 






102 






sec 




168 






103 






sbc 


i mage__he i ght^ x 


169 


* Initial ize 


variables showing & moving 


104 


:6 




sta 


ypos i t i on^ X 


170 


* images across the screen. 


105 






1 nc 


i mage__i ndex 


171 






106 






Ida 


1 mage_index 


172 


in it images 


Idx «0 


107 






cmp 


number_of_i mages 


173 


: 1 Ida 


def _vel X, X 


108 






bcc 


: move_l oop 


174 


sta 


xvelocity^x ;X velocity 


109 






rts 


175 


Ida 


def _vel y , x 


110 










176 


sta 


yvelocity.x ;V velocity 


111 










177 


Ida 


def _posx, X 


112 


* Invert 


X vel oci tu for i 1 1 us i on of bounce . 


178 


sta 


xpos it ion ^x ; starting X 


113 










179 


Ida 


def _posy^ x 


114 


1 nvert 


_xvel Ida xvelocitu.x 


180 


sta 


yposition.x ; starting Y 


115 






eor 


«$ffff 


181 


Ida 


def _ui i dth , x 


116 






Inc 




182 


sta 


image_width,x ; in pixels 



1 OQ 

loo 


1 da 


oeT ^Dy vew i at-n, x 


n A Q 

c49 


rts 


1 OA 

Ion 


st-a 


i mage_bytew i dth, X ; in bytes 


250 






1 da 


def _he i ght, x 


251 


>♦< 


loD 


sta 


i inage_he i ght , x ; i n scan 1 i nes 


252 


* Find size of shires screen and where it is. 


187 


txa 




253 


* Rlso, determine where row address table is. 


188 


asl 




254 


* This rtn takes advantage of default port 


189 


tay 




255 


* when Qu i ckDraw f i rst starts up . 


190 


1 da 


def _i mage, y 


256 


191 


sta 


image_adrs,y ;addr of image 


257 


plot_setup "GetPortLoc «sh ires loc info 


1 QO 
l^C 


1 oa 


OeT _ 1 mage^d , y 


cDo 


uevrtddress '•i 


183 


sta 


image_adrs+2,y 


259 


pull long rowadrs_table 


19n 


inx 




OCA 

260 


r vs 


195 


inx 




261 




1 QA 
Iv^D 


cpx 


«nflXinflQES*2 


COC 




197 


bcc 


:1 


263 


* Start up some tools needed for program. 


198 


txa 




C.OH 




199 


Isr 




265 


* Output : 


200 


sta 


number_of_i mages 


O d c 


* carry : set i f some sort of error occured 


201 


rts 




267 




202 






268 


dostartup __TLStartUp 


203 


♦Defaults. Note that velocities should never 


269 


_n 1 otar vUp 


204 


*be > 2: images will leave trails otherwise. 


C. {%} 


1 II lo var^up 


205 






271 


pi a 


206 


def_velx da 


1.-2 


c rc. 


sta Program ID 


207 def_vely da 


1,-2 


2 ro 


c 1 c 


208 def_posx da 


4.300 




adc «^ 11010 


209 def_posy da 


10. 100 


c 


Sua rrivaveiu 


Pin 


def_uiidth da 


16,16 


C rO 




211 


def _byteui i dth 


da 8,8 


C r r 


^ uev c i rec V page lor yu tCKuraw l^^v/v? worvnj . 


212 


def_height da 


15, 15 


C r O 


213 


def_ image adrl 


bas i c_i mage__l , bas i c__ i mage_2 


c 


iMewnanc i e ^^■ovk) ^ rrogram lu; ^^c%i i>j ; «<o 


214 






CO0 


pul 1 1 ong deref__ptr 


215 


* 




OQ 1 
CO 1 


bcs : X 


216 


* Put byte-oriented image onto shires scrn. 


doc. 


1 da LdereT J3 vr j 


217 


* Assumes image is even « of bytes wide. 


C.OO 


pha 


218 






OO/l 


pushword *0 ; 320 mode 


219 


plot_image Ida 


pi ot_ypos 


C.O>J 


pushword ^0 ; screen w i dth 


220 


asl 


;V -> index 


COO 


pushword ProgramID 


221 


tay 




CO r 


__Wuo var vup 


222 


Ida 


plot_xpos 


ooo 
coo 


bcs : X 


223 


Isr 


.pixels to bytes 


2o9 


Jsr plot^setup 


224 


clc 




Cn70 


C 1 c 


225 


adc 


[rowadrs_tab 1 e] , y 


Cs3l 


: X rts 


226 


sta 


screen__ptr 


OOO 

coc 




227 


Ida 


sh i res^adrs-*"?: 


OQO 
COO 


* Shut down tools started and dispose of any 


228 


sta 


screen_ptr+2 


294 


* private memory we may have allocated. 


229 


:row_loop Idy 


«0 


caO 




230 


:byte_loop Ida 


[i mage_ptr] , y 


296 


doshutdown _QDShutDown 


231 


sta 


[screen^ptr] , y 


CO r 




232 


i ny 




COO 


TIMShutDown ProgramID 


233 


i ny 




O OQ 
COO 


__n 1 onu^uown 


234 


cpy 


plot_bytewidth 


O00 


1 Lonu vUown 


235 


bcc 


: by te_l oop 




r vs 


236 


Ida 


image_ptr 


o rn o 
O0C 




237 


clc 








238 


adc 


plot_bytewidth 




VI 1 i ^ 111 re vv4r rid <i2>\<'ii rsc^ vol ii ovoii ctu i 


239 


sta 


1 mage_ptr 


305 


* else it returns a zero. 


240 


bcc 


:1 


306 




241 


1 nc 


Image _ptr+2 


307 


* Output: 


242 


:1 Ida 


screen_ptr 


308 


* Carry: set if key pressed (key in fl.reg). 


243 


clc 




309 




244 


adc 


sh i res_byte_iu idth 


310 


keyboard = $e0c000 


245 


sta 


screen_ptr 


311 


keystrobe = $e0c010 


246 






312 




247 


dec 


pi ot_he i ght 


313 


read_key sep «$20 


248 


bne 


: rouj_l oop 


314 


1 da 1 keyboard 




315 
316 
317 
318 
313 
320 
321 
322 
323 
324 
325 
326 
327 
328 
329 
330 
331 
332 
333 
334 
335 
336 
337 
338 
333 
340 
341 
342 
343 
344 
345 
346 
347 
348 
349 
350 
351 
352 



bpl 

stal 

rep 

and 
cmp 
rts 



Keystrobe 
«$20 
n$ff 
«$80 



Do a short pause. 



* 

* Input: 

* fl.reg:« of 5000th sec intervals to wait. 



gs_speed_control = $e0c036 



pause_a_moment 
tax 
beq 
Sep 
Idal 
and 
sta 
Idal 
and 
stal 
rep 
Jsr 
dex 
bne 
Sep 
Ida 
oral 
stal 



: lua i t 



rep 
rts 



: X 

«$20 

gs_speed_control 
<t$80 

old_speed 
gs_speed_contro 1 
«$7f 

gs_speed_contr o 1 

«$20 

uia i t 

:uia i t 
«$20 

ol d_speed 
gs_speed_contro 1 
gs_speed_contro 1 
«$20 



0=no delay 



* Typical wait loop^ waits for .005 sec 



376 
377 
378 
379 
380 



* Motion boundaries Cin pixels) 

1 ef t_boundary ds 2 
r i ght_boundary ds 2 



381 
382 
383 
384 
385 
386 
387 
388 
383 
390 
391 
392 
393 
394 
395 
396 
397 
398 
399 
400 
401 
402 
403 
404 
405 
406 
407 
408 
409 
410 
411 
412 
413 
414 
415 
416 
417 
418 



353 wait 


Sep 


«$20 




419 


354 


Ida 


«42 




420 


355 : 1 


pha 






421 


356 :2 


sec 






422 


357 


sbc 


«1 




423 


358 


bne 


:2 




424 


359 


pla 






425 


360 


sec 






426 


361 


sbc 


«1 




427 


352 


bne 


: 1 




428 


363 


rep 


«$20 




429 


364 


rts 






430 


365 








431 


366 * 








432 


367 * variables. 






433 


368 








434 


369 quitparms adrl 







435 


370 


da 


$0000 


;not restartable 


436 


371 ProgramID ds 


2 




437 


372 Private ID ds 


2 




438 


373 number 


_of_ images ds 2 


; « of i mages 


439 


374 image 


index ds 


2 


; 1 oop i ndex 


440 


375 old_speed ds 


2 


441 



442 
443 
444 
445 
446 



top_boundary ds 2 
bottom_boundary ds 2 

* Plot__image inputs. 

plot_ypos ds 2 
plot__xpos ds 2 
plot_height ds 2 
plot_bytew idth ds 2 

* Screen location record. 

sh i res 1 oc i nf o 
portSCB ds 2 
shires_adrs ds 4 
sh i res_byte_w i dth ds 2 

ds 4 
sh i res_he i ght ds 2 
shires width ds 2 



; space f i 1 1 er 



♦ Image arrays 

xposition ds 
yposition ds 
xvelocity ds 
yvelocity ds 
i mage_he i ght ds 
image_width ds 
i mage_bytew i dth 
image_adrs ds 



MflXinflGES*2 
nflXinflGES*2 

nflxinflGES*2 
nflxinflGEs*2 
nflxinflGEs*2 
nflxinflGES*2 

ds nflXinflGES*2 

nflxinflGES*4 



*Basic images, ea 16 pxls[8 bytes)wide by 15 
♦lines h i . PI ot_Image assumes even byte width 

basic_image_l hex 0000000000000000 

hex 0000000000000000 

hex 000aaaaaaaaaa000 

hex 00aaaaaaaaaaaa00 

hex 00aaaaa00aaaaa00 

hex 00aaaa0000aaaa00 

hex 00aaa000000aaa00 

hex 00aa00000000aa00 

hex 00aaa000000aaa00 

hex 00aaaa0000aaaa00 

hex 00aaaaa00aaaaa00 

hex 00aaaaaaaaaaaa00 

hex 000aaaaaaaaaa000 

hex 0000000000000000 

hex 0000000000000000 

basic_image_2 hex 0000000000000000 

" hex 0000000000000000 

hex 0000000440000000 

hex 0000004444000000 

hex 0000044444400000 

hex 0000444444440000 

hex 0004444444444000 

hex 0044444444444400 

hex 0004444444444000 

hex 0000444444440000 

hex 0000044444400000 

hex 0000004444000000 

hex 0000000440000000 

hex 0000000000000000 

hex 0000000000000000 



Our Very Own Stuff 

• 8/16 on Disk* 

The magazine you are now holding in your hands is but a subset of the material on the 8/16 disk. We have combed 
the BBS's and data services across the country to collect the best of the public domain and shareware offerings 
for programmers. Not only that, but we have extra articles and source code written by our staff. With DLT16 and 
DLT8 (Display Launcher Thingamajigs) to guide you, you can read articles, display graphics, and even launch 
applications. 

1 year - $69.95 6 months - $39.95 3 months - $2 1 



• Shem The Penman's Guide To Interactive Fiction • 

Tom Weishaar said it best in the October '88 edition of Open-Apple (now A2-CentraD: 

"[This] ...is one of thoese rare educational software packages that does things in the classroom with a computer 
that can't be done any other way. It*s the foundation for a semester long course... Like all the best educational 
software. Shem the Penman's Guide comes with a student manual on disk, where it can be shortened, 
lengthened, or otherwise modified..." 

Tom forgot to mention that this is a terrific introduction to writing interactive fiction for programmers, too. 
Author Chet Day is a professional writer (go buy Hacker at your nearest book store!) and an educator who is as 
conemed with the content of your interactive fiction program as with the form. This package is fun, entertain- 
ing, and useful. It includes Applesoft, ZBasic, and Micol Advanced Basic "shells" which will drive your creations 
- $39.95 (both 5.25" and 3.5" disks supplied). P.S. The advantage to the ZBasic and Micol versions is that with 
the easy integration of text and graphics provided in those langauges, you can easily load a graphic and overlay 
text in the appropriate spots. 



• ProTools™ • 

Fast approaching its first birthday, our ProTools library for ZBasic programmers has grown into a mature and 
powerful product. It's bigger than ever, too. inCider's Joe Abemathy called it, "...the only way to go for ZBasic 
programmers." 

ProTools includes a text based anda double high resolution graphics based desktop interface (pull-down menus, 
windows, mouse tracking, etc.) Both desktops support quick- key equivalents for menu items, too! We've added 
a third desktop package in version 2.5 of ProTools, too. This one is mouseless, meaning that it is entirely keyboard 
driven and therefore much more compact than its predecessors. 

Mr. Ed, our "any window" text editor, will provide AppleWorks^^ command compatible text editing in the screen 
rectangle of your choice. With no limit to edit field length, Mr.Ed is like having a word processor available as 
part of your prograuh Our newest version of Mr.Ed will even scroll the window if you want to support edit fields 
longer than your designated rectangle! 




ProTools contains literally scores of additional functions and routines, including: 



• FRAME. FN 

• GETMACHID 



• SMART.INPUT.FN 



• GETKEY.FN 

• DIALOG 



• SCROLL.MENU.FN 

• SCREENDUMP80 

• CRYPT 

• LINE GRAPH 

• READTEXT 

• PATHCK 



• SAVE_SCREEN 



• SETSPEED 



• DATETIME 

• ONLINE 



• BAR CHART 

• PASSWORD 

• VERTMENU 



ProTools is $39.95 (5.25" and 3.5" disks supplied). 

NOTE: If you are already a ProTools owner, be sure and send us a blank disk and a SASE so that we can give 
you your free update. The new additions and bug fixes make it very worthwhile! 



If you need to write a database in ZBasic (or any other BASIC that supports multi- statement functions), ZIndex 
is the mechanism that will free you from the memory restrictions Imposed by 128K Apple IFs. ZTndex manages 
B+Tree indices for the key fields of your choice (it creates an index file for each key field) . You can look up records 
in virtually any order with nearly RAM speeds, even though your data files are disk based. 

ZIndex supports up to 65535 records and can perform key insertions, deletions, finds, find next, find previous, 
find first, find last, and find with record. The function can be used to index an existing database or a new one. 
It can also index unique keys or non-unique keys. 

ZJndex retails for $39.95 and is shipped with both 3.5" and 5.25" disks. (Note: The current version is written 
specifically for ZBasic. Conversion to other BASICS may involve some translation.) 



Micol Systems, Canada has produced two BASICS that should be of interest to anyone looking to empower their 
Apple II. Micol Advanced Basic Ile/IIc is for 128K Apples, and Micol Advanced Basic GS is for the Apple Ilgs. 
One of the many features that recommend these two are that the GS version is upwardly compatible with lie/ 
lie version. This means your 8 bit software can be quickly ported to the GS and almost immediately take 
advantage of the additional speed, memory, and graphics modes of the machine. 

Both versions integrate graphics and text with equal ease, and both versions also provide local variables, multi- 
statement functions, terrific editors, multi-parameter subroutines, structured loops, and just about anything 
else a mature, modem language should have. The GS version has recently been extended to provide a simple 
interface for the creation of desktop-based programs. 

MAB Ile/IIc $69.95 MAB GS $99.95 



Our guarantee: Ariel Publishing guarantees your satisfaction with our entire product line (software and 
publications). If you are ever dissatisfied with one of our products, we will cheerfully refund the amount you 
paid on your request. Furthermore, we will ship the software packages to you on 30 day approval, meaning that 
you'll not have to pay until youVe had the stuff for nearly a month. Of course, we take checks. VISA and 
MasterCard up front, too. Just write to: Ariel Publishing, Box 398, Pateros. WA 98846 or call (509) 923-2249. 



• ZIndex • (NEW! - and shipping) 



• Micol Advanced Basic • 



Them's the BRKs: 

Relocation in 8 bit assembly 

by Jerry Kindall, 8-bit Editor 



I had the pleasure of meeting Bob Sander-Cederlof at 
the A2-Central Developer Conference last July in Kan- 
sas City. Bob brought with him to the conference a 
number of leftover Apple Assembly Lines back issues, 
and was giving them away to anyone who wanted them. 
In the resulting feeding frenzy, I managed to snatch a 
nearly complete set. Td been a deprived child; Fd heard 
of AAL but never actually seen an issue. Now I know 
what I was missing. 

One interesting article, published way back in June of 
1982, was entitled "Implementing New Opcodes Using 
BRK" and demonstrated how to use the BRK opcode to 
tie machine-language routines into your programs as if 
they were new opcodes. The three new opcodes de- 
scribed in the article were designed to help you to write 
completely relocatable code. However, the BRK handler 
was required to be at a fixed address (instead of being 
relocatable along with the rest of the program), and the 
three new instructions, while useful, offered only rela- 
tive JMP, JSR, and LEA (load effective address), 

I thought it would be fun to generalize Bob*s idea into a 
multipurpose relocation routine. (OK, so my idea of 
"fun" is a little strange.) My variation on this theme 
allows you to turn any three-byte 6502 opcode into a 
relocatable instruction by preceding it with a BRK 
opcode. The run-time relocator can also handle imme- 
diate-mode instructions that load a register with an 
address, an addressing mode which has traditionally 
been the bane of relocatable programming. 

Add some macros, and it's almost as if the 6502 
suddenly sprouted a whole new relative addressing 
mode. Programs written with the run-time relocator 
can be loaded and run at ANY address, without modi- 
fication. 



The Code 

Rather than trying to start out by explaining how the 
program works and how to use it. 111 give you the code 
first and then try to explain it. There's no need to 



assemble this code; it's designed to be used as a Merlin 
PUT file. Save it to disk as RTR. 



Listing 1 



1 




1st on 


2 




3 




**** 


4 




Run-Time Relocator **** 


5 




by Jerry Kindall **** 


6 






7 




for 8/16 


8 




Merlin 8 Assembler ♦>♦«♦* 


9 






10 




11 




1st off 


12 






13 




org $800 


14 






15 


♦Instal 1 


BRK handler by finding current run 


16 


*addr of 


this routine and storing it into 


17 


*the BRK 


vector at $3F0-$3F1 


18 






19 


RTR 


php ;save ress on stack 


20 




pha 


21 




txa 


22 




pha 


23 




tya 


24 




pha 


25 




Ida $3F0 




; save 


current BRK vector 


26 




pha 


27 




Ida $3F1 


28 




pha 


29 


: getadr 


jsr $FF58 ;call known RTS 


30 




tsx 




jun-pop address onto stack 


31 




dex 


32 




dex 


33 




txs 


34 




pi a 




; figure low byte of BRK handler 


35 




cl c 


36 




ado «RTR_PROC- : getadr-2 


37 




sta $3F0 


38 




pi a 




; figure hi byte of BRK handler 


39 




adc «/RTR PROC- : getadr-2 


40 




sta $3F1 


41 




pi a 




; get 


old BRK vector 


42 




brk 



; and save in hold area 



wmm, mm 



sta RTR_0LDB+1 
pla 

brk 

sta RTR„OLDB 

pla 

; restore all registers 
tay 
pla 
tax 
pla 
pip 
brk 

Jmp RTR^CONT 
; cont i nue m \ th program 

RTR^OLDB ds 2 

;hold area for old BRK vector 

•* Process BRK reqst by relocating 3-byte 
♦* i nstruct i on f o 1 1 oui i ng the BRK . 



43 
44 
45 
46 
47 

48 
49 
50 
51 
52 
53 
54 

55 
56 

57 
58 
59 

60 * 

61 ^Special case opcodes: BRK (00)= a real BRK, 

62 *l\IOP (Efl) = immediate mode relocation 
63 

64 RTR^PROC sec 

; point $3fl to BRK 

65 Ida $3fl 

66 sbc «2 

67 sta $3fl 

68 bcs : 

69 dec $3B 

70 :0 Idy m 

71 Ida C$3flD,y 
;get opcode 

72 beq : brk 

; i t ' s a REAL BRK 

73 cmp «$Efl 

74 bne : adjust 
75 

76 * fidjust 2 immediate C2~byte) instructions 

77 

78 iny 

79 iny 

80 sec 

; subtract out assembly address 

81 Ida C$3fl],y 

82 sbc ^ : proc 

83 tax 
;save low byte 

84 i ny 

; subtract out hi byte 

85 iny 

86 Ida C$3R).y 

87 sbc «/:proc 

88 pha 

; save h i byte 

89 dey 

;add in runtime address 

90 dey 

91 clc 

92 txa 

93 ado $3F0 

94 sta [$3flD,y 
;modify low byte 

95 i ny 



96 
97 

98 
99 

100 
101 
102 
103 
104 
105 
105 
107 
108 
109 
110 

111 
112 
113 

114 

115 
116 
117 

118 

119 
120 
121 
122 

123 
124 

125 
126 

127 
128 

129 
130 
131 

132 
the 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 



my 
pi a 

; add in hi 
adc 
sta 

; mod i f y hi 
clc 
bcc 



byte 
$3F1 
[$3fl).y 
byte 

: goback 



* Handle BRK instruction 

:brk Jmp $Ffl59 ;do a REAL BRK 

* Adjust absolute C3-byte) instruction 

: adjust iny 
sec 

; subtract out assembly address 
Ida [$3fl),y 
sbc » : proc 
tax 

;save low byte 
i ny 

; subtract out hi byte 
Ida [$3R).y 
sbc «/:proc 
pha 

jsave hi byte 
dey 

;add in runtime address 
clc 
txa 

adc $3F0 
sta [$3fl),y 
; modify low byte 

i ny 



;add 



pla 

in hi byte 



adc 
sta 

; modify hi 



$3F1 
C$3fl),y 
byte 



: goback Idy «0 
;NOP out the BRK 
1 da «$Efl 
sta ($3flD,y 
Jsr $FF3F 
; restore registers 
Jmp l$3fl) 

i nstruct i on 



;go do 



* Routine to deinstall Run-Time Relocator 

* Call using BRK followed by JSR RTRJINS 

* No registers are changed 



RTR DINS 



php 
pha 
brk 
Ida 
sta 
brk 
Ida 
sta 
pla 
pip 



RTR.OLDB 
$3F0 

RTR_0LDB+1 
$3F1 



148 rts 
149 

150 RTR^CONT 

151 1st on 



Using The Relocator 

To include the run-time relocator in your own pro- 
grams, all you need to do is include a PUT RTR as the 
first statement in your source code. Do NOT include a 
REL or ORG statement. If you wish to assemble to disk, 
include the DSK psuedo-op before the PUT RTR. 

In your program, insert a BRK opcode before each 
absolute or absolute indexed instruction which refer- 
ences an address within your code. You can insert a 
BRK before ANY three-byte instruction — JSR, JMP, 
EOR, LDA, or even BIT. Here's a simple example using 
this capability. 

Listing 2 



1 


put 


rtr 


2 






3 


cout = 


$FDED 


4 

5 


start Idx 


«0 ;set index to zero 


6 


brk 






; rel ocate 


next instruction 


7 


1 oop 1 da 


text.x ; get character 


8 


beq 


exit ;end of string 


9 


Jsr 


cout ; print character 


10 


1 nx 


;pt to next character 


11 


bne 


loop 




; always Cwhen string <255 chars) 


12 


exit rts 




13 






14 


text asc 


"This is an example run-time 




rel ocat i on 


program . " 


15 


hex 


8D00 



Check out the BRK instruction in line 6. When that line 
is executed, the run-time relocator gets control and 
patches the next statement to work at the program*s 
current address. The BRK opcode is replaced with a 
NOP so the relocator won't erroneously adjust the 
already-corrected instruction the next time it*s exe- 
cuted. 

Line 9's JSR is NOT preceded by a BRK instruction. 
That's because COUT is not a location within your 
program; it's an absolute ROM location. You definitely 
don't want to mess with the address of a call to the ROM . 
Only instructions which reference locations within your 
program should be preceded by a BRK. Also remember 
that branching instructions (BNE, etc.) are already 



relocatable and do not need to be prefaced with a BRK. 

Note that the BNE instruction in line 1 1 branches back 
to line 7, not line 6. The first time line 6 is executed, it'll 
be replaced with a NOP instruction — so there's no 
reason to branch back to a NOP the next time through. 



Immediate Mode Instructions 

As I mentioned earlier, the mn-time relocator has the 
ability to adjust immediate-mode instructions as well. 
Here's a short example of that: 



Listing 3 








1 




put 


rtr 




2 










3 


prntax 




$F941 




4 


cout 




$FDED 




5 










6 


start 


Ida 


«"$" 


; pr i nt do! 1 ar s i gn 


7 




Jsr 


cout 




8 




brk 




; rel ocate 


S 




nop 




; effective address 


10 




Ida 


«rtr 






;get 


address of relocator 


11 




Idx 


«/rtr 




12 




Jsr 


prntax 


; print in hex 


13 




Ida 


4t$8D 


; print CR 


14 




Jsr 


cout 




16 




rts 







The purpose of the above code is to print the run-time 
address of the program (in hex notation) on the screen. 
Note that line &s BRK is followed in line 9 by a NOP. This 
is a special flag to the run-time relocator that two 
immediate mode instructions follow. This is similar to 
the "effective address" mode on some other processors. 
(In fact, I chose NOP as the effective address flag 
because its hex code is EA — an acronym for effective 
address. Some might call this pretzel logic.) 

In line 10, we load the Accumulator with the low byte of 
the label RTR; in line 1 1 , the high byte of the same label 
is loaded into the X register. The label RTR is defined in 
the relocator source code (see line 18 of the first source 
listing) as the beginning of the executable code. The 
run-time relocator will assume that the operand of the 
first instruction is the low byte of an address, and the 
operand of the second is the high byte of the same 
address. So this sequence of instructions loads the 
Accumulator and the X-register with the address of the 
first instruction in the program, adjusted for the 
program*s mn-time address. 



Notice that (in line 13) we load the accumulator with a 
constant number. $8D is the code for a carriage return, 
and should remain constant no matter where in mem- 
ory the program runs. 

This feature of the run-time relocator is designed for 

loading both bytes of an address into a pair of registers. 
If you just need to load the high byte of an address, you 
can do something like this: 



10 brk 

1 1 nop 

12 Ida Isabel ;load loiu byte 

13 Ida «/ label replace ui/hl byte 

You must specify the same label in lines 12 and 13 so 
that the relocator can properly adjust for code that isn*t 
on a page boundary. To get the low byte only, try this: 

10 brk 

1 1 nop 

12 Ida «label ;load low byte 

13 bit ;do almost nothing 



The BIT in line 13 will get adjusted, but notice that it's 
a page zero instruction, not an immediate instruction. 
The relocator doesn't care and will adjust its operand 
anyway; thus, the BIT instruction will operate on some 
arbitrary location on page zero, changing your Negative 
and Zero status flags but leaving the actual value in the 
accumulator unchanged. 



Really Breaking 

If you really want to execute a BRK instruction, just 
include two of them in a row, like this: 

50 brk ;come to a screeching halt 

51 brk 

This will bring your program to a stop in the Monitor 
with a program counter and register display. You'll 
notice that the program counter has been adjusted to 
point to the first BRK instruction, rather than two bytes 
past that address as it usually does when a BRK is 
executed. 



De-installing the Run-Time Relocator 

Sometime before your program ends, youll probably 
want to disconnect the run-time relocator from the BRK 
vector and reconnect the standard Apple BRK routine 



(or whatever BRK-handler was active when the run- 
time reloca'tor began execution). A relocatable JSR to 
RTR_DINS will do the trick for you: 

60 brk ; de- i nsta 1 1 RTR 

61 Jsr RTR^DINS 

Remember, you won't be able to use the run-time 
relocator after de-installing it, so be sure that you really 
are getting ready to exit your program before calling 
RTR_DINS. RTR_DINS does not change any registers. 



How It Works 

The run-time relocator uses five global labels: RTR, 
RTR_OLDB, RTR^PROC, RTR_DINS, and RTR.CONT. 
All the rest are local labels, and in several places I used 
hex addresses instead of EQU*d labels. The goal was to 
be able to PUT the code without having to remember 
what labels I had "used up" in the relocator. 

The run-time relocator uses some tricky code, but really 
isn't that complex. The main keys to understanding 
what is going on are the ORG $800 statement (line 13), 
which specifies where the program is "set up** intemally 
to run, and some knowledge of how the BRK handler 
works. When a BRK instruction is encountered, the 
6502 jumps to the NMI handler in the Monitor. The 
Monitor saves the program counter and all registers, 
then decides whether the interrupt was caused by a 
BRK instruction or an actual NMI, and passes control 
to the appropriate handler through a page 3 vector. We 
can take advantage of the saved information in our BRK 
handler, and we can use any registers we like as long as 
we call the Monitor routine to reload the registers before 
we exit. With this information in mind, let's look at the 
program's main "chunks" of code. 

Lines 19 through 54 are what gets executed when you 
run your program. First, all registers and the current 
contents of the BRK vector are saved on the stack. Line 
29 calls a known RTS instruction in the ROM, then lines 
30-33 adjust the stack pointer so the retum address 
can be retrieved with PLAs. The retum address is 
adjusted to point to our BRK handler, then stored into 
the BRK vector (lines 34-40). The old contents of the 
BRK vector are then pulled off the stack and stored into 
RTR__OLDB, using the run-time relocator itself to do the 
dirty work of relocating the STA instructions. Finally, 
in lines 47-52, the registers are restored, and the main 
program (which begins at RTR^CONT) is entered via a 
relocatable JMP instruction, again using the run-time 



relocator. 

Lines 64-74 are the main BRK handler routing. The 
very first thing the relocator does is to back up the 
program counter ($3A-$3B) by two bytes, because the 
BRK instruction always generates a return address two 
bytes past the BRK. In lines 70-74 I handle the two 
special cases, effective addressing and true BRK. If 
neither is found, the instruction is assumed to be three 
bytes in length. 

Lines 78- 1 1 handle effective addressing. You*ll need to 
keep a close eye on the Y register to understand this 
routine. Treating the operands of the two immediate- 
mode instructions as an address, this routine subtracts 
out the assembly-time address of the BRK routine, then 
adds in the run-time address of the BRK handler as 
stored in the BRK vector. The result is stored back into 
the actual program code, and the routine exits through 
line 104. No checking is done to ensure that there really 
are two immediate-mode instructions present; the relo- 
cator assumes you know what you Ye doing. 

Line 105 handles a true BRK (two BRK instructions in 
a row) by JMPing to $FA59. the Monitor ROM's default 
BRK handler. This ROM routine displays the registers 
and program counter and drops into the Monitor. 

The handler for the three-byte instructions (lines 109- 
126) works in essentially the same way as the effective 
addressing handler at lines 78-101. The Y register is 
incremented and decremented to point at slightly differ- 
ent bytes, but the function is the same. Once again no 
opcode checking is done; it*s up to you to make sure you 
Include a three byte instruction adfter a BRK. 

The exit routine, used by both the effective address 
handler and the absolute address handler, is at line 
128. This short routine stores a NOP over the BRK 
instruction which called the relocator, restores all reg- 
isters with a call to $FF3F. and JMPs back into the main 
program. Notice that the BRK handler (line 81) does 
NOT unpatch the BRK. If it did. the two BRKs (which 
mean a true BRK) would tum into one BRK, which, on 
subsequent executions, would cause the next instruc- 
tion to be adjusted! 



CONCLUSION 

The run-time relocator is a slick way to write code that 
can be instantly run at any location without having to 



mess around with adjusting it. It*s easy to use, and 
flexible too. 

Naturally, it*s not perfect. If you move the program to 
another memory location after it's been executed once, 
it won't work because aU the BRKs have been patched 
out. Your code does end up slightly larger because of 
the BRK interpreter and the needed BRKs. You have to 
be careful if you're fond of self-modifying code because 
the BRK handler does some modifying of its own. If the 
user presses Reset, an instruction may wind up half- 
relocated. Et cetera. 

It is, however, very well suited to programs that will be 
loaded into memory at an arbitrary address, executed 
once, and then abandoned, such as short 
BASIC.SYSTEM utility programs. Besides which, mn- 
time relocation is a neat thing you can do with your 
Apple, and it's fun and instructive to boot. Isn't that 
enough of a reason to play around with it? 

i^^^^'^ired Guns 

8 / 1 6 is providing a free service to all programmers (who 
are subscribers!): placement of a complimentary "situ- 
ation wanted" ad. If you're available for hire and looking 
for a programming job (from full-time to freelance), a 
listing in this directory is your ticket to work. The ads 
are open to both 8 and 16 bit authors and are limited to 
120 words or less. Be sure to give your address, phone 
number, and email addresses, and specify how much of 
a job you're after (part-time? full-time? royalty-based? 
etc). Send it to Situation Wanted, c/o Ariel Publishing, 
Box 398, Pateros, WA 98846 



David Ely. 4567 W. 159th St. Lawndale, CA 90260. 213-371-4350 
eves, or leave message. GEnie: [DDELY], AOL: "DaveEly". Expe- 
rienced in 8 and 16 bit assembly, C, Forth and BASIC. Available for 
hourly or flat fee contract work on ail Apple 11 platforms (ligs 
preferred). Have experience in writing desktop and classical applica- 
tions in 8 or 1 6 bit environments, hardware and firmware interfacing, 
patching and program maintenance. Will work individually or as a 
part if a group. 

Jeff Holcomb, 1 8250 Marsh Ln, #51 5. Dallas, Tx 75287. (21 4) 306- 
0710, leave message. GEnie: [Applied. Eng], AOL: "AE Jeff". I am 



Msiffcsih, mm 



looking for part-time work in my spare time. I prefer 1 6-bit programs 
but I am familiar with 8-bit. Strengths are GS/OS, desktop applica- 
tions, and sound programming. I have also worked with hardware/ 
firmware, desk accessories, CDevs, and inits. 

Tom Hoover, Rt 1 Box 362, Lorena, TX, 76655, 817-752-9731 
(day), 817-666-7605 (night). GEnie: Tom-Hoover; AOL: THoover; 
Pro-Beagle, Pro-APA, or Pro-Carolina: thoover. Interests/strengths 
are 8-bit utility programs, including TimeOut(tm) applications, written 
in assembly language. Looking for "part-time" work only, to be done 
in my spare time. 

Jay Jennings, 14-9125 Robinson #2A, Overland Park, KS, 66212. 
(913) 642-5396 late evenings or early mornings. GEnie: [A2.JAY] or 
[PUNKWARE]. Apple ligs assembly language programmer. Looking 
for short term projects, typically 2-4 weeks. Could be convinced to do 
longer projects in some cases. Familiar with console, modem, and 
network programming, desk accessories, programming utilities, 
data bases, etc. GS/OS only. No DOS 3.3 and no 8-bit (unless the 
money is extremely good and there's a company car involved). 

Jim Lazar, 1109 Niesen Road, Port Washington, Wl 53074, 414- 
284-4838 nights, 414-781-6700 days. AOL: "WinkieJim", GEnie: 
[WINKIEJIM]. Strengths include: GS/OS and ProDOS 8 work, desk 

Well be running those folks with k 



top applications, CDAs, NDAs. INITs. Prefer working in 6502 or 
6581 6 Assembly. Have experience with large and small programs, 
utilities, games, disk copy routines and writing documentation. 
Nibble, inCider and Call-A.P.P.L.E. have published my work. Prefer 
1 6-bit, but will do 8-bit work. Type of work depends on the situation, 
would consider full-time for career move/benefits, othenA/ise 25 hrs/ 
month (flexible). 

Stephen P. Lepisto, 1 2907 Strathern St., N. Hollywood, CA 91 605, 
818-503-2939. GEnie: S.LEPISTO. Available for full-time and part- 
time contract work (flat rate or royalties). Experienced in 6502 to 
65816 assembly, BASIC and C. Can work in these or quickly learn 
new languages and hardware (some experience with UNIX, MS- 
DOS, 8086 assembly). Experience in games, utilities, educational, 
applications. Lots of experience in porting programs to Apples. 
Programmed Hacker II (64k Apple II), Labyrinth (128k Apple), 
Firepower GS and others. Can also write technical articles. 

Chris McKlnsey, 3401 Alder Drive, Tacoma, WA, 98439, 206-588- 
7985, GEnie: C.MCKINSEY. Experience in programming 16-bit 
(65c81 6) games. Strengths include complex super hi-res animation, 
sound work (digitized and sequenced), and firmware. Looking for 
new ligs game to develop or the porting of games from other 
computers to the ligs. 

names starting with M-Z next month! 
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E WANT YOUR BEST! 





I o you've written a great piece of Apple II or Apple IIgs software, 
but you're not sure how to turn all that hard work into hard cash. 
I You're wary of shareware and you've been snubbed by other 
publishers. 

I et us take a look at your work! We are the publishers of Sof tdisk 
and Sof tdisk G-S, monthly collections of software sold by 
I subscription, and we're looking for top-notch Apple II and Apple 
IIGS software. We respond promptly, pay well, and are actually fun to 
work with! 



To submit your software for possible publication, send in your best to: 

SOFTDISK PUBLISHING, INC 

606 Common St. 
Shreveport, LA 71101 
ATTN: Apple Submissions 



Here's a short list of 
what will put a gleam in 
our eyes (and money in 
your pocket)! For more 
details, contact Jay 
Wilbur at (318) 221- 
5134. 

Teacher Utilities 

Gradebook 

Test Maker/ Scorer 

Attendance Keeper 

Award Maker 
Educational Lessons 

Geometry 

Math 

Physics 

Science 
Resume Maker 
Graphical Music Maker 
Recipe Card Filer 
Magazine Indexer 
AppleWorks DB Reader 
Art Clipper DA 
Paint Program 
Cartoon Construction Kit 
Fonts 
Clip Art 

Desk Accessories 



The Sensational Lasers 

Apple lle/llc Compatible 

m $375 



Includes 10 free 
software programs! 



%i!SS^ Now Includes 

COPY II PLUS 




The Laser 128® features fuli Apple® II compatibility with an internal disk drive, serial, parallel, modem, and 
mouse ports. When you're ready to expand your system, there's an external drive port and expansion slot. The 
Laser 128 even includes 10 free software packages! Take advantage of this exceptional value today $375 



Super High Speed Option! 

only $425 

The LASER 128EX has all the features of the 
LASER 128, plus a triple speed processor and 
memory expansion to 1MB $425.00 

The LASER 128EX/2 has all the features of the 
LASER 128EX, plus MIDI, Clock and Daisy 
Chain Drive Controller $465.00 

DISK DRIVES 

• 5.25 LASER/Apple 11c $ 99.00 

• 5.25 Apple 11e $ 99.00 

• 3.50 Apple 800K $179.00 

• 5.25 LASER Daisy Chain . . .<Za2^ $109.00 

• 3.50 LASER Daisy Chain . . . #7qp^S179.00 



Save Money by Buying 
a Complete Package! 

THE STAR a LASER 128 Computer with 12" 
Monochrome Monitor and the LASER 145E 
Printer $645.00 

THE SUPERSTAR a LASER 128 Computer with 
14" RGB Color Monitor and the LASER 145E 
Printer $825.00 

ACCESSORIES 

• 12" Monochrome Monitor $ 89.00 

• 14" RGB Color Monitor $249.00 

• LASER 190E Printer $219.00 

• LASER 145E Printer ^ZSJ^ $189.00 

• Mouse $ 59.00 

• Joystick (3) Button .......$ 29.00 

• 1200/2400 Baud Modem Auto .... $149.00 



U.S.A. MICRO 



YOUR DIRECT SOURCE FOR APPLE 
AND IBM COMPATIBLE COMPUTERS 



3 2888 Bluff Street, Suite 257 • Boulder, CO. 80301 
Add 3% Shipping • Colorado Residents Add 3% Tax 

Your satisfaction is our guarantee! 

Laser 128 is a registeted trademark of Video Technology Computers. Inc Apple, Apple 



4> Phone Orders: 1-800-654-5426 

8 - 5 Mountain Time • No Surcharge on Visa or MasterCard Orders! 

Customer Service: 1-800-537-8596 • In Colorado: (303) 938-9089 
Apple lie and Imagewnter are registered trademarks o! Apple Computer Inc 



http://apple2scans 



